Resource Parameters

Basics

Web runtime values such as HTTP requests and cookies that require ResourceObjects are passed directly to the method arguments.

For requests from HTTP, the arguments of the onGet and onPost methods are passed $_GET and $_POST, respectively, depending on the variable name. For example, $id in the following is passed $_GET['id']. Arguments passed as strings when the input is HTTP will be casted to the specified type.

class Index extends ResourceObject
{
    public function onGet(int $id): static
    {
        // ....

Parameter type

Scalar parameters

All parameters passed via HTTP are strings, but if you specify a non-string type such as int, it will be cast.

Array parameters

Parameters can be nested data ¹; data sent as JSON or nested query strings can be received as arrays.

class Index extends ResourceObject
{
    public function onPost(array $user):static
    {
        $name = $user['name']; // bear

Class Parameters

Parameters can also be received in a dedicated Input class.

class Index extends ResourceObject
{
    public function onPost(User $user): static
    {
        $name = $user->name; // bear

The Input class is defined in advance with parameters as public properties.

<?php

namespace Vendor\App\Input;

final class User
{
    public int $id;
    public string $name;
}

At this time, if there is a constructor, it will be called. ²

<?php

namespace Vendor\App\Input;

final class User
{
    public function __constrcut(
        public readonly int $id,
        public readonly string $name
    } {}
}

The Input class can implement methods to summarize and validate input data.

Enum parameters

You can specify an enumerated type in PHP8.1 to limit the possible values.

enum IceCreamId: int
{
    case VANILLA = 1;
    case PISTACHIO = 2;
}

class Index extends ResourceObject
{
    public function onGet(IceCreamId $iceCreamId): static
    {
        $id = $iceCreamId->value // 1 or 2

In the above case, if anything other than 1 or 2 is passed, a ParameterInvalidEnumException will be raised.

Web context binding

PHP superglobals such as $_GET and $_COOKIE can be bound to method arguments instead of being retrieved in the method.

use Ray\WebContextParam\Annotation\QueryParam;

class News extends ResourceObject
{
    public function foo(
    	  #[QueryParam('id')] string $id
    ): static {
       // $id = $_GET['id'];

Others can be done by binding the values of $_ENV, $_POST, and $_SERVER.

use Ray\WebContextParam\Annotation\QueryParam;
use Ray\WebContextParam\Annotation\CookieParam;
use Ray\WebContextParam\Annotation\EnvParam;
use Ray\WebContextParam\Annotation\FormParam;
use Ray\WebContextParam\Annotation\ServerParam;

class News extends ResourceObject
{
    public function onGet(
        #[QueryParam('id')] string $userId,            // $_GET['id'];
        #[CookieParam('id')] string $tokenId = "0000", // $_COOKIE['id'] or "0000" when unset;
        #[EnvParam('app_mode')] string $app_mode,      // $_ENV['app_mode'];
        #[FormParam('token')] string $token,           // $_POST['token'];
        #[ServerParam('SERVER_NAME') string $server    // $_SERVER['SERVER_NAME'];
    ): static {

When the client specifies a value, the specified value takes precedence and the bound value is invalid. This is useful for testing.

Resource Binding

The #[ResourceParam] annotation can be used to bind the results of other resource requests to the method argument.

use BEAR\Resource\Annotation\ResourceParam;

class News extends ResourceObject
{
    public function onGet(
        #[ResourceParam('app://self//login#nickname') string $name
    ): static {

In this example, when the method is called, it makes a get request to the login resource and receives $body['nickname'] with $name.

Content negotiation

The content-type header of HTTP requests is supported. The application/json and x-www-form-urlencoded media types are determined and values are passed to the parameters. ³.