2.path-parameters.md

Note

Attributes used in this document

• #[Param] - supported by the open api service ✅

Path parameters

You can specify variable parts in your route paths.
Those variable parts can then be passed to your route handler function as parameters.

<?php
use function CatPaw\Core\anyError;
use function CatPaw\Core\success;
use CatPaw\Core\Unsafe;
use CatPaw\Web\Server;

function handler(string $name) {
    return  success("This is $name's about page.");
}

function main(): Unsafe {
    return anyError(function(){
        $server = Server::get();
        $server->router->get('/about/{name}', handler(...))->try();
        $server->start()->try();
    });
}

Types

Since they're just regular php parameters, path parameters can specify a primitive type.

The server will enforce this type matching, meaning all incoming requests to the given route must comply with the types of the path parameters.

The server will respond with 400 Bad Request when an incoming request doesn't comply with a path parameter's type.

Given this definition

<?php
use function CatPaw\Core\anyError;
use function CatPaw\Core\success;
use CatPaw\Core\Unsafe;
use CatPaw\Web\Server;

function handler(int $age) {
    return success("This cat is now $age years old.");
}

function main(): Unsafe {
    return anyError(function(){
        $server = Server::get();
        $server->router->post('/set/age/{age}', handler(...))->try();
        $server->start()->try();
    });
}

Sending POST /set/age/yes will result into a 400 Bad Request answer from the server.
Instead, an appropriate request would be POST /set/age/3.

More customization

Sometimes you need more than php primitives to enforce your path parameters' values.

Use CatPaw\Web\Attributes\Param to modify the matching pattern for your path parameters.

<?php
use function CatPaw\Core\anyError;
use function CatPaw\Core\success;
use CatPaw\Web\Attributes\Param;
use CatPaw\Core\Unsafe;
use CatPaw\Web\Server;

function handler(#[Param('\w{3,15}')] string $name) {
    return  success("This is $name's about page.");
}

function main(): Unsafe {
    return anyError(function(){
        $server = Server::get();
        $server->router->get('/about/{name}', handler(...))->try();
        $server->start()->try();
    });
}

The above path parameter will match strings that are at least 3 characters and at most 15 characters long.

More on variable parts

As you would expect, a symbolic path can contain multiple variable parts

<?php
use function CatPaw\Core\anyError;
use function CatPaw\Core\success;
use CatPaw\Core\Unsafe;
use CatPaw\Web\Server;

function handler(string $name, string $childName) {
    return  success("This is $childName's about page, who is $name's kitten.");
}

function main(): Unsafe {
    return anyError(function(){
        $server = Server::get();
        $server->router->get('/about/{name}/child/{childName}', handler(...))->try();
        $server->start()->try();
    });
}

But variable parts are more powerful than that because they are not bound to any common web path rules.

Variable parts can be defined anywhere within the symbolic path, even as a partial part of a sub-path.

'/about/{name}/child-{childName}'

That is a valid symbolic path and string $childName would still be a valid path parameter.

As a matter of fact we don't need the inner slashes (/) at all, the following is also valid

'/parent:{name},child:{childName}'

Note

The first forward slash is always required.