Skip to content

Feat: Param aliases #252

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

Merged
ChiragAgg5k merged 5 commits into from
May 5, 2026
+220 −12
Merged

Feat: Param aliases #252

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
772bea8
parma alias + tests
Meldiron May 4, 2026
ffa12f2
Simplify implementation
Meldiron May 4, 2026
a59317c
implement e2e tests
Meldiron May 4, 2026
4439705
fix url param aliases
Meldiron May 4, 2026
258e326
Use stable servers 0.4.0
ChiragAgg5k May 5, 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 @@ -32,7 +32,7 @@
"require": {
"php": ">=8.3",
"utopia-php/di": "0.3.*",
"utopia-php/servers": "0.3.*",
"utopia-php/servers": "0.4.0",
"utopia-php/compression": "0.1.*",
"utopia-php/telemetry": "0.2.*",
"utopia-php/validators": "0.2.*"
Expand Down
14 changes: 7 additions & 7 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.

28 changes: 24 additions & 4 deletions src/Http/Http.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -699,15 +699,35 @@ protected function getArguments(Hook $hook, array $values, array $requestParams)
{
$arguments = [];
foreach ($hook->getParams() as $key => $param) { // Get value from route or request object
$existsInRequest = \array_key_exists($key, $requestParams);
$existsInValues = \array_key_exists($key, $values);
$requestKey = $key;
if (!\array_key_exists($key, $requestParams) && !empty($param['aliases'])) {
foreach ($param['aliases'] as $alias) {
if (\array_key_exists($alias, $requestParams)) {
$requestKey = $alias;
break;
}
}
}

$valuesKey = $key;
if (!\array_key_exists($key, $values) && !empty($param['aliases'])) {
foreach ($param['aliases'] as $alias) {
if (\array_key_exists($alias, $values)) {
$valuesKey = $alias;
break;
}
}
}

$existsInRequest = \array_key_exists($requestKey, $requestParams);
$existsInValues = \array_key_exists($valuesKey, $values);
$paramExists = $existsInRequest || $existsInValues;

$arg = $existsInRequest ? $requestParams[$key] : $param['default'];
$arg = $existsInRequest ? $requestParams[$requestKey] : $param['default'];
if (\is_callable($arg) && !\is_string($arg)) {
$arg = \call_user_func_array($arg, array_values($this->getResources($param['injections'])));
}
$value = $existsInValues ? $values[$key] : $arg;
$value = $existsInValues ? $values[$valuesKey] : $arg;

if (!$param['skipValidation']) {
if (!$paramExists && !$param['optional']) {
Expand Down
188 changes: 188 additions & 0 deletions tests/HttpTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -290,6 +290,194 @@ public function testCanAddAndExecuteHooks(): void
$this->assertSame('x-def', $result);
}

public function testCanResolveParamAliases(): void
{
$this->http
->error()
->inject('error')
->action(function ($error) {
echo 'error-' . $error->getMessage();
});

$savedGet = $_GET;
$savedPost = $_POST;
$savedMethod = $_SERVER['REQUEST_METHOD'] ?? null;

try {
// GET request: alias resolves from $_GET when canonical key is absent
$_GET = ['xAlias' => 'from-alias'];
$_SERVER['REQUEST_METHOD'] = 'GET';

$route = new Route('GET', '/path');
$route
->param('x', 'x-def', new Text(200), 'x param', true, aliases: ['xAlias', 'xLegacy'])
->action(function ($x) {
echo $x;
});

ob_start();
$this->http->execute($route, new Request(), new Response());
$result = ob_get_contents();
ob_end_clean();

$this->assertSame('from-alias', $result);

// GET request: canonical key wins when both are present in $_GET
$_GET = ['x' => 'canonical', 'xAlias' => 'aliased'];

$route = new Route('GET', '/path');
$route
->param('x', 'x-def', new Text(200), 'x param', true, aliases: ['xAlias'])
->action(function ($x) {
echo $x;
});

ob_start();
$this->http->execute($route, new Request(), new Response());
$result = ob_get_contents();
ob_end_clean();

$this->assertSame('canonical', $result);

// GET request: first matching alias wins when multiple are present in $_GET
$_GET = ['xAlias2' => 'second', 'xAlias1' => 'first'];

$route = new Route('GET', '/path');
$route
->param('x', 'x-def', new Text(200), 'x param', true, aliases: ['xAlias1', 'xAlias2'])
->action(function ($x) {
echo $x;
});

ob_start();
$this->http->execute($route, new Request(), new Response());
$result = ob_get_contents();
ob_end_clean();

$this->assertSame('first', $result);

// GET request: falls back to default when neither canonical nor any alias is in $_GET
$_GET = ['unrelated' => 'value'];

$route = new Route('GET', '/path');
$route
->param('x', 'x-def', new Text(200), 'x param', true, aliases: ['xAlias'])
->action(function ($x) {
echo $x;
});

ob_start();
$this->http->execute($route, new Request(), new Response());
$result = ob_get_contents();
ob_end_clean();

$this->assertSame('x-def', $result);

// GET request: required param throws when neither canonical nor any alias is in $_GET
$_GET = ['unrelated' => 'value'];

$route = new Route('GET', '/path');
$route
->param('x', '', new Text(200), 'x param', false, aliases: ['xAlias'])
->action(function ($x) {
echo $x;
});

ob_start();
$this->http->execute($route, new Request(), new Response());
$result = ob_get_contents();
ob_end_clean();

$this->assertSame('error-Param "x" is not optional.', $result);

// GET request: validation runs against the aliased value and reports the canonical key
$_GET = ['xAlias' => 'too-long'];

$route = new Route('GET', '/path');
$route
->param('x', '', new Text(1, min: 0), 'x param', false, aliases: ['xAlias'])
->action(function ($x) {
echo $x;
});

ob_start();
$this->http->execute($route, new Request(), new Response());
$result = ob_get_contents();
ob_end_clean();

$this->assertSame('error-Invalid `x` param: Value must be a valid string and no longer than 1 chars', $result);

// POST request: alias resolves from $_POST body
$_GET = [];
$_POST = ['xAlias' => 'posted-alias'];
$_SERVER['REQUEST_METHOD'] = 'POST';

$route = new Route('POST', '/path');
$route
->param('x', 'x-def', new Text(200), 'x param', true, aliases: ['xAlias'])
->action(function ($x) {
echo $x;
});

ob_start();
$this->http->execute($route, new Request(), new Response());
$result = ob_get_contents();
ob_end_clean();

$this->assertSame('posted-alias', $result);

// URL path: alias resolves the placeholder name to the canonical param key
$_GET = [];
$_POST = [];
$_SERVER['REQUEST_METHOD'] = 'GET';
$_SERVER['REQUEST_URI'] = '/users/abc-123';

$route = Http::get('/users/:userId')
->param('user_id', '', new Text(200), 'user id', false, aliases: ['userId'])
->action(function ($user_id) {
echo $user_id;
});

$matched = $this->http->match(new Request());
$this->assertSame($route, $matched);

ob_start();
$this->http->execute($matched, new Request(), new Response());
$result = ob_get_contents();
ob_end_clean();

$this->assertSame('abc-123', $result);

// URL path value beats request param when both are present (path-level override)
$_GET = ['user_id' => 'from-query'];
$_SERVER['REQUEST_URI'] = '/users-2/from-path';

$route = Http::get('/users-2/:userId')
->param('user_id', '', new Text(200), 'user id', false, aliases: ['userId'])
->action(function ($user_id) {
echo $user_id;
});

$matched = $this->http->match(new Request());
$this->assertSame($route, $matched);

ob_start();
$this->http->execute($matched, new Request(), new Response());
$result = ob_get_contents();
ob_end_clean();

$this->assertSame('from-path', $result);
} finally {
$_GET = $savedGet;
$_POST = $savedPost;
if ($savedMethod === null) {
unset($_SERVER['REQUEST_METHOD']);
} else {
$_SERVER['REQUEST_METHOD'] = $savedMethod;
}
}
}

public function testAllowRouteOverrides(): void
{
Http::setAllowOverride(false);
Expand Down