Problem
URLs, localization maps and bizproc codes are passed as raw string / array across the SDK
service signatures (e.g. handlerUrl, serverUrl, oauthServerUrl, localized NAME /
DESCRIPTION). There is no shared typing, and validation is duplicated or absent — only
Core\Credentials\WebhookUrl validates URLs (via filter_var). This is inconsistent with the
SDK's value-object approach for other primitives (money, IP, phone) and lets invalid values reach
the transport layer.
#493 introduced the reusable value objects and applied Stage 1 to the Robot service as the
reference implementation:
Core\ValueObjects\Url
Core\ValueObjects\LocalizedString
Services\Workflows\ValueObjects\RobotCode and ActivityCode
bizproc.robot.add / bizproc.robot.update now accept string|Url, string|RobotCode and array|LocalizedString.
This issue tracks rolling the same pattern out to the rest of the SDK and then executing Stage 2.
Proposed solution
- Stage 1 (URLs): widen the remaining URL parameters to
string|Url (raw strings wrapped and validated internally); document raw-string usage as soft-deprecated. Refactor Core\Credentials\WebhookUrl to build on top of Core\ValueObjects\Url so URL validation lives in one place.
- Stage 1 (bizproc codes): wire
ActivityCode into bizproc.activity.add / bizproc.activity.update as string|ActivityCode, mirroring the RobotCode migration.
- Stage 1 (localization): widen the remaining localized
array parameters (e.g. the Activity NAME / DESCRIPTION) to array|LocalizedString.
- Shared helper: extract the
resolveUrl() / resolveRobotCode() / resolveLocalizedString() helpers introduced in Robot into a shared location (trait or AbstractService).
- Stage 2 (breaking, next major release): type all URL, code and localization parameters as their value objects only; remove the
string / array unions.
Acceptance criteria
Depends on #493 (introduces the value objects and the Stage 1 reference implementation).
Problem
URLs, localization maps and bizproc codes are passed as raw
string/arrayacross the SDKservice signatures (e.g.
handlerUrl,serverUrl,oauthServerUrl, localizedNAME/DESCRIPTION). There is no shared typing, and validation is duplicated or absent — onlyCore\Credentials\WebhookUrlvalidates URLs (viafilter_var). This is inconsistent with theSDK's value-object approach for other primitives (money, IP, phone) and lets invalid values reach
the transport layer.
#493 introduced the reusable value objects and applied Stage 1 to the
Robotservice as thereference implementation:
Core\ValueObjects\UrlCore\ValueObjects\LocalizedStringServices\Workflows\ValueObjects\RobotCodeandActivityCodebizproc.robot.add/bizproc.robot.updatenow acceptstring|Url,string|RobotCodeandarray|LocalizedString.This issue tracks rolling the same pattern out to the rest of the SDK and then executing Stage 2.
Proposed solution
string|Url(raw strings wrapped and validated internally); document raw-string usage as soft-deprecated. RefactorCore\Credentials\WebhookUrlto build on top ofCore\ValueObjects\Urlso URL validation lives in one place.ActivityCodeintobizproc.activity.add/bizproc.activity.updateasstring|ActivityCode, mirroring theRobotCodemigration.arrayparameters (e.g. theActivityNAME/DESCRIPTION) toarray|LocalizedString.resolveUrl()/resolveRobotCode()/resolveLocalizedString()helpers introduced inRobotinto a shared location (trait orAbstractService).string/arrayunions.Acceptance criteria
Core\ValueObjects\Urlis reused everywhere a URL is accepted as inputCore\ValueObjects\LocalizedStringis reused everywhere a localized string map is acceptedCore\Credentials\WebhookUrlreusesUrl(no duplicated validation)resolve*()helpers live in one shared placestring|Url,array|LocalizedString)CHANGELOG.mdis updated with the issue linkDepends on #493 (introduces the value objects and the Stage 1 reference implementation).