Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ChiragAgg5k wants to merge 2 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
777b3f2
feat: add typed Enum DTO for param metadata
ChiragAgg5k May 20, 2026
c490c9a
chore: pin utopia-php/servers to feat-param-enum-metadata dev branch
ChiragAgg5k May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion composer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
"utopia-php/cli": "0.23.*",
"utopia-php/http": "^2.0@RC",
"utopia-php/queue": "0.18.*",
"utopia-php/servers": "0.4.*"
"utopia-php/servers": "dev-feat-param-enum-metadata as 0.4.0"
Copy link
Copy Markdown

@greptile-apps greptile-apps Bot May 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 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.*").

},
"require-dev": {
"phpunit/phpunit": "^9.3",
Expand Down
38 changes: 23 additions & 15 deletions composer.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 3 additions & 1 deletion src/Platform/Action.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,9 +170,10 @@ public function getParams(): array
* @param bool $deprecated
* @param string $example
* @param array $aliases
* @param Enum|null $enum
* @return self
*/
public function param(string $key, mixed $default, Validator|callable $validator, string $description = '', bool $optional = false, array $injections = [], bool $skipValidation = false, bool $deprecated = false, string $example = '', array $aliases = []): self
public function param(string $key, mixed $default, Validator|callable $validator, string $description = '', bool $optional = false, array $injections = [], bool $skipValidation = false, bool $deprecated = false, string $example = '', array $aliases = [], ?Enum $enum = null): self
{
$param = [
'default' => $default,
Expand All @@ -184,6 +185,7 @@ public function param(string $key, mixed $default, Validator|callable $validator
'deprecated' => $deprecated, // TODO: @Meldiron implement tests
'example' => $example,
'aliases' => $aliases,
'enum' => $enum,
];
$this->options['param:'.$key] = array_merge($param, ['type' => 'param']);
$this->params[$key] = $param;
Expand Down
21 changes: 21 additions & 0 deletions src/Platform/Enum.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
<?php

namespace Utopia\Platform;

/**
* Enum metadata for whitelist-backed parameters.
*/
final readonly class Enum
{
/**
* @param string|null $name Generated enum name.
* @param array<string, string>|null $map Mapping of whitelist values to generated enum case names.
* @param list<string>|null $exclude Whitelist values to omit from generated enums.
*/
public function __construct(
public ?string $name = null,
public ?array $map = null,
public ?array $exclude = null,
) {
}
}
6 changes: 3 additions & 3 deletions src/Platform/Platform.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ protected function initHttp(array $services): void
switch ($option['type']) {
case 'param':
$key = substr($key, stripos($key, ':') + 1);
$hook->param($key, $option['default'], $option['validator'], $option['description'], $option['optional'], $option['injections'], $option['skipValidation'], $option['deprecated'], $option['example'], aliases: $option['aliases'] ?? []);
$hook->param($key, $option['default'], $option['validator'], $option['description'], $option['optional'], $option['injections'], $option['skipValidation'], $option['deprecated'], $option['example'], aliases: $option['aliases'] ?? [], enum: $option['enum'] ?? null);
break;
case 'injection':
$hook->inject($option['name']);
Expand Down Expand Up @@ -165,7 +165,7 @@ protected function initTasks(array $services): void
switch ($option['type']) {
case 'param':
$key = substr($key, stripos($key, ':') + 1);
$hook->param($key, $option['default'], $option['validator'], $option['description'], $option['optional'], $option['injections'], $option['skipValidation'], $option['deprecated'], $option['example'], aliases: $option['aliases'] ?? []);
$hook->param($key, $option['default'], $option['validator'], $option['description'], $option['optional'], $option['injections'], $option['skipValidation'], $option['deprecated'], $option['example'], aliases: $option['aliases'] ?? [], enum: $option['enum'] ?? null);
break;
case 'injection':
$hook->inject($option['name']);
Expand Down Expand Up @@ -222,7 +222,7 @@ protected function initWorker(array $services, string $workerName): void
switch ($option['type']) {
case 'param':
$key = substr($key, stripos($key, ':') + 1);
$hook->param($key, $option['default'], $option['validator'], $option['description'], $option['optional'], $option['injections'], $option['skipValidation'], $option['deprecated'], $option['example'], aliases: $option['aliases'] ?? []);
$hook->param($key, $option['default'], $option['validator'], $option['description'], $option['optional'], $option['injections'], $option['skipValidation'], $option['deprecated'], $option['example'], aliases: $option['aliases'] ?? [], enum: $option['enum'] ?? null);
break;
case 'injection':
$hook->inject($option['name']);
Expand Down
5 changes: 4 additions & 1 deletion tests/Platform/TestActionWithParams.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,11 @@
namespace Utopia\Tests;

use Utopia\Platform\Action;
use Utopia\Platform\Enum;
use Utopia\Validator\Boolean;
use Utopia\Validator\Range;
use Utopia\Validator\Text;
use Utopia\Validator\WhiteList;

class TestActionWithParams extends Action
{
Expand All @@ -19,8 +21,9 @@ public function __construct()
->param('age', 0, new Range(0, 150), 'User age.', true, example: '25')
->param('active', false, new Boolean(true), 'Is active.', true, deprecated: true, example: 'true')
->param('email', '', new Text(256), 'User email.', true, aliases: ['emailAddress', 'userEmail'], example: 'user@example.com')
->param('status', 'draft', new WhiteList(['draft', 'published']), 'Status.', optional: true, enum: new Enum(name: 'ArticleStatus', map: ['draft' => 'Draft', 'published' => 'Published']))
->inject('response')
->callback(function ($name, $age, $active, $email, $response) {
->callback(function ($name, $age, $active, $email, $status, $response) {
$response->send('OK');
});
}
Expand Down
17 changes: 17 additions & 0 deletions tests/e2e/HTTPServicesTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,5 +167,22 @@ public function testActionParamFieldsForwardedToRoute()
// Verify params without aliases have empty array
$this->assertArrayHasKey('aliases', $params['name'], 'Param name should have aliases key');
$this->assertEquals([], $params['name']['aliases']);

// Verify enum is forwarded to Route params
$this->assertArrayHasKey('enum', $params['status'], 'Param status should have enum key on Route');
$this->assertInstanceOf(\Utopia\Platform\Enum::class, $params['status']['enum']);
$this->assertEquals('ArticleStatus', $params['status']['enum']->name);
$this->assertEquals(['draft' => 'Draft', 'published' => 'Published'], $params['status']['enum']->map);

// Verify enum is stored on Action params
$action = new TestActionWithParams();
$actionParams = $action->getParams();

$this->assertInstanceOf(\Utopia\Platform\Enum::class, $actionParams['status']['enum']);
$this->assertEquals('ArticleStatus', $actionParams['status']['enum']->name);
$this->assertEquals(['draft' => 'Draft', 'published' => 'Published'], $actionParams['status']['enum']->map);

// Verify params without enum are null on Action
$this->assertNull($actionParams['name']['enum']);
}
}
Loading