feat: add typed Enum DTO to Action::param()

[ChiragAgg5k]

What does this PR do?

Adds an optional typed Enum DTO parameter to Utopia\Platform\Action::param() for attaching SDK enum metadata to whitelist-backed parameters.

Instead of a generic meta bag (which risks becoming a junk drawer for unrelated data), the parameter accepts a scoped Utopia\Platform\Enum value:

->param(
    'status',
    'draft',
    new WhiteList(['draft', 'published']),
    'Status.',
    optional: true,
    enum: new Enum(
        name: 'ArticleStatus',
        map: ['draft' => 'Draft', 'published' => 'Published'],
    ),
)

Enum contains:

• $name — generated enum name
• $map — mapping of whitelist values to case names (array<string, string>)
• $exclude — whitelist values to omit from generated enums

Utopia stores and forwards the DTO but does not interpret it. Enforcement (e.g. "whitelist must have enum") is left to consumer generators.

Why not a generic meta array?

A generic meta array would couple Utopia to consumer-specific concepts and invite abuse as a catch-all dump for unrelated data. A typed, scoped DTO keeps the API clean and forces intentional design for future metadata needs.

Test Plan

• Existing positional and named-argument calls to param() remain valid (backward-compatible).
• enum defaults to null when not provided.
• enum is stored in both $this->params[$key] and $this->options['param:'.$key].
• enum is intentionally not forwarded to Route/CLI/Worker hooks.
• Added e2e assertions verifying enum presence on Action params and absence on Route params.

Related PRs and Issues

N/A — small framework-level API expansion.

Checklist

• Have you read the Contributing Guidelines on issues?
• If the PR is related to an issue in another repository, please provide a link.

[greptile-apps]

Greptile Summary

This PR introduces a typed Enum DTO (Utopia\Platform\Enum) that can be attached to Action::param() calls to carry SDK enum metadata for whitelist-backed parameters. The enum field is stored on both $this->params and $this->options, and is forwarded to Route/CLI/Worker hooks via the three init* methods in Platform.php.

• New Enum DTO — final readonly class with optional name, map, and exclude fields; fully nullable so consumers can attach partial metadata as needed.
• Action::param() extended — ?Enum $enum = null appended as a named parameter, maintaining full backward compatibility with all existing positional and named-argument call sites.
• Platform forwarding — all three initHttp, initTasks, and initWorker paths pass enum: through to the underlying hook, coordinated with bumps to utopia-php/servers 0.4.1, utopia-php/http rc3, utopia-php/cli 0.23.4, and utopia-php/queue 0.18.4 that add matching support.

Confidence Score: 5/5

Safe to merge — the change is a backward-compatible addition of an optional parameter with no effect on existing call sites or runtime validation logic.

The Enum DTO is a pure data carrier with no side effects; Action::param() remains fully backward-compatible; the Platform forwarding paths are consistent across all three init methods; and the updated dependency versions are stable patch or RC releases. The only gap found is in test coverage, which does not affect production behavior.

No files require special attention beyond the minor test coverage gap in tests/e2e/HTTPServicesTest.php.

Important Files Changed

Filename	Overview
src/Platform/Enum.php	New final readonly DTO with three optional nullable fields (name, map, exclude). Clean, minimal, no issues.
src/Platform/Action.php	Adds optional ?Enum $enum = null to param() signature and stores it in both $params and $options. Backward-compatible addition.
src/Platform/Platform.php	All three init methods (HTTP, Tasks, Worker) updated to forward enum to the underlying hook's param(). Consistent and correct.
tests/e2e/HTTPServicesTest.php	Adds enum assertions for Route and Action params; actionParamKeys array omits enum, leaving a gap in the all-fields-forwarded coverage loop.
tests/Platform/TestActionWithParams.php	Adds a status param with Enum DTO to the test fixture; optional:true and default 'draft' are consistent with the WhiteList validator.
composer.lock	Several utopia-php packages bumped to stable patch/RC versions (servers 0.4.1, http rc3, cli 0.23.4, queue 0.18.4, validators 0.2.4); previously flagged dev-branch dependency is resolved.

_{Reviews (8): Last reviewed commit: "Update Utopia server dependencies" | Re-trigger Greptile}