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 class and threads it as an optional parameter through Action::param(), storing it on both $this->params and $this->options, and forwarding it to HTTP/CLI/Worker hooks via Platform.php.

• src/Platform/Enum.php: New final readonly DTO with nullable name, map, and exclude properties, providing scoped enum metadata for whitelist-backed parameters.
• src/Platform/Action.php / Platform.php: enum added as a trailing optional parameter to param() (backward-compatible) and threaded through all three hook initialisation paths (initHttp, initTasks, initWorker).
• composer.json: utopia-php/servers is temporarily pinned to a dev feature branch (dev-feat-param-enum-metadata) because the servers package's param() must also accept the new enum argument; this dependency needs to resolve to a stable release before the PR merges.

Confidence Score: 4/5

The logic changes are sound, but the PR cannot safely land on main while utopia-php/servers is pinned to an unmerged feature branch.

The Enum DTO, Action changes, and Platform forwarding are all clean and backward-compatible. The blocking concern is that utopia-php/servers is pointing at a dev branch commit rather than a released version — the feature works today but the branch could drift or be deleted, and the dev stability flag it introduces could affect downstream consumers.

composer.json — the dev-branch servers dependency must be replaced with a stable release version before merging.

Important Files Changed

Filename	Overview
composer.json	Pins utopia-php/servers to an unmerged feature branch (dev-feat-param-enum-metadata); must be resolved before this PR lands on main.
src/Platform/Enum.php	New final readonly DTO with three nullable constructor properties (name, map, exclude); clean and minimal.
src/Platform/Action.php	Adds optional ?Enum $enum = null to param() as a trailing parameter; fully backward-compatible, stored in both $this->params and $this->options.
src/Platform/Platform.php	Threads enum through to $hook->param() in initHttp, initTasks, and initWorker; depends on utopia-php/servers accepting the new enum parameter (currently only on a dev branch).
tests/Platform/TestActionWithParams.php	Adds a status param fixture with enum metadata; default 'draft' is valid within the WhiteList, and optional: true is set.
tests/e2e/HTTPServicesTest.php	Adds enum assertions for both Action and Route params, but the comprehensive per-param keys list omits 'enum', leaving a small coverage gap.

_{Reviews (6): Last reviewed commit: "chore: pin utopia-php/servers to feat-pa..." | Re-trigger Greptile}

[greptile-apps]

Dev-branch dependency should not be merged to main

utopia-php/servers is pinned to dev-feat-param-enum-metadata as 0.4.0, an unmerged feature branch. While the composer.lock pins to a specific commit today (333e93c5), the stability-flags entry forces minimum-stability: dev for this package. If this PR is merged before the utopia-php/servers feature branch is itself merged and a stable version tagged, any downstream consumer that runs composer update could pull unexpected dev-channel releases, and the branch ref could disappear or be force-pushed. This PR should wait for the servers PR to land and a stable release be cut, then update composer.json back to a stable version constraint (e.g. "utopia-php/servers": "0.5.*").