Skip to content

Adopt Url/LocalizedString/code value objects across SDK signatures #533

Description

@mesilov

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

  • Core\ValueObjects\Url is reused everywhere a URL is accepted as input
  • Core\ValueObjects\LocalizedString is reused everywhere a localized string map is accepted
  • Core\Credentials\WebhookUrl reuses Url (no duplicated validation)
  • The resolve*() helpers live in one shared place
  • Stage 1 preserves full backward compatibility (string|Url, array|LocalizedString)
  • Stage 2 is scheduled for the next major and removes the unions
  • Unit tests cover the migrations
  • CHANGELOG.md is updated with the issue link

Depends on #493 (introduces the value objects and the Stage 1 reference implementation).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions