Check attributes

---

1Overview

1.1Validation attributes

Temma provides several attributes used to validate incoming data:

• \Temma\Attributes\Check\Params: Validates parameters present in the URL.
• \Temma\Attributes\Check\Get: Validates data received as GET parameters.
• \Temma\Attributes\Check\Post: Validates data received as POST parameters.
• \Temma\Attributes\Check\Files: Validates uploaded files.
• \Temma\Attributes\Check\Payload: Validates data sent in the request body.

These attributes are wrappers that call the validateParams(), validateInput(), validatePayload() and validateFiles() methods of the Request object. Validations are based on contracts in the format expected by the DataFilter object.

---

1.2Common parameters

Some parameters are common to all of these attributes:

• $strict: (bool) Enables strict validation mode (false by default).
• $redirect: (string) URL to redirect the user to if the data is not valid.
• $redirectVar: (string) Name of the template variable containing the redirection URL.
• $flashVar : (string) Name of the flash variable that will contain information in case of redirection. The content of the flash variable depends on the attribute used (see below).

---

1.3Redirection priority

When the data is not valid, the attribute can redirect the user to another page.
To determine the redirection URL, the following priority order is applied:

1. If the $redirect parameter is defined, it is used.
2. If the $redirectVar parameter is defined and contains the name of an existing, non-empty template variable, its value is used.
3. If the etc/temma.php file contains an extended x-security configuration with a redirect key, its value is used.

If no redirection URL is found, a 403 error is returned.

---

2Params

2.1Params: overview

This attribute validates the parameters received by an action (or by all actions of a controller).
It is a wrapper around the validateParams() method of the Request object.

---

2.2Params: specific parameters

• $contract : (string|array) Name of the contract defined in the configuration file (see documentation), or name of a validation object, or list of contracts (one contract per parameter).
• $flashVar : (string) Name of the flash variable that will contain a copy of the received parameters if the user is redirected.

---

2.3Params : examples

use \Temma\Attributes\Check\Params as TµCheckParams;

/*
 * All controller actions must have one parameter of type "int"
 * and one parameter of type "email".
 */
#[TµCheckParams(['int', 'email'])]
class Actions extends \Temma\Web\Controller {
    // ...
}

use \Temma\Attributes\Check\Params as TµCheckParams;

class Actions extends \Temma\Web\Controller {
    // this action expects a positive integer parameter
    // and a string of 12 characters or fewer
    #[TµCheckParams(['int; min: 0', 'string; maxLen: 12'])]
    public function doSomething(int $i, string $s) {
        // ...
    }

    // expects an integer parameter and an email address,
    // with strict validation mode enabled, while allowing additional parameters
    #[TµCheckParams(
        [
            'int',
            'email',
            '...'
        ],
        strict: true,
    )]
    public function action2(int $id, string $mail, float $amount, string $name) {
        // ...
    }

    // expects a negative integer and a string, with redirection to a specific URL
    // in case of error, storing the received parameters
    // in a flash variable
    #[TµCheckParams(
        ['int; max: 0', 'string'],
        redirect: '/path/to/error',
        flashVar: 'getErr',
    )]
    public function action3(int $id, string $value) {
        // ...
    }

    // parameters must validate the contract named "deleteUserParameters"
    // in the configuration file, defined as follows:
    // 'validationTypes' => [
    //     'deleteUserParameters' => [
    //         'type'   => 'list',
    //         'values' => [
    //             'int; min: 1',
    //             'hash; algo: sha256',
    //             'string; minLen: 2',
    //         ]
    //     ]
    // ]
    #[TµCheckParams('deleteUserParameters')]
    public function deleteUser(int $userId, string $checkHash, string $login) {
        // ...
    }
}

---

3Get

3.1Get: overview

This attribute validates the GET parameters received by a controller or an action.
It is a wrapper around the validateParams() method of the Request object.

---

3.2Get: specific parameters

• $contract : (string|array) Name of the contract defined in the configuration file (see documentation), or name of a validation object, or associative array whose keys are GET parameter names and whose values are validation contracts.
• $flashVar : (string) Name of the flash variable that will contain a copy of the received GET data if the user is redirected.

---

3.3Get: examples

use \Temma\Attributes\Check\Get as TµCheckGet;

/*
 * All controller actions must receive GET parameters
 * "id" (int type) and "mail" (email type).
 */
#[TµCheckGet([
  'id'   => 'int',
  'mail' => 'email',
])]
class Actions extends \Temma\Web\Controller {
    // ...
}

use \Temma\Attributes\Check\Get as TµCheckGet;

class Actions extends \Temma\Web\Controller {
    // this action expects a GET parameter "id" (without specifying the type)
    #[TµCheckGet(['id'])]
    public function getList() {
        // ...
    }

    // expects an "id" parameter and a "name" parameter (string with minimum 3 characters)
    // with strict validation mode enabled, while allowing additional parameters
    #[TµCheckGet(
        [
            'id',
            'name' => 'string; minLen: 3; maxLen: 20',
            '...'
        ],
        strict: true,
    )]
    public function removeItem(int $id) {
        // ...
    }

    // expects an integer 'id' and an optional string 'name',
    // with redirection to a specific URL,
    // and storing received GET data in a flash variable
    #[TµCheckGet(
        [
            'id'    => 'int',
            'name?' => 'string', 
        ],
        redirect: '/path/to/error',
        flashVar: 'getErr',
    )]
    public function defineItem(int $id, mixed $value) {
        // ...
    }

    // GET parameters must validate the contract named "internalUserData" in
    // the configuration file, defined as follows:
    // 'validationTypes' => [
    //     'internalUserData' => [
    //         'login' => 'string; minLen: 2',
    //         'email' => 'email; mask: @mydomain.com$',
    //         'name'  => 'string; minLen: 2',
    //     ]
    // ]
    #[TµCheckGet('internalUserData')]
    public function updateUser(int $userId) {
        // ...
    }
}

---

4Post

4.1Post: overview

This attribute validates POST parameters received by a controller or an action.
It is a wrapper around the validateParams() method of the Request object.

---

4.2Post: specific parameters

• $contract : (string|array) Name of the contract defined in the configuration file (see documentation), or name of a validation object, or associative array whose keys are POST parameter names and whose values are validation contracts.
• $flashVar : (string) Name of the flash variable that will contain a copy of the received POST data if the user is redirected.

---

4.3Post: examples

use \Temma\Attributes\Check\Post as TµCheckPost;

/*
 * All controller actions must receive POST parameters
 * "id" (int type) and "mail" (email type).
 */
#[TµCheckPost([
  'id'   => 'int',
  'mail' => 'email',
])]
class Actions extends \Temma\Web\Controller {
    // ...
}

use \Temma\Attributes\Check\Post as TµCheckPost;

class Actions extends \Temma\Web\Controller {
    // this action expects a POST parameter "id" (without specifying the type)
    #[TµCheckPost(['id'])]
    public function getList() {
        // ...
    }

    // expects an "id" parameter and a "name" parameter (string with minimum 3 characters)
    #[TµCheckPost([
        'id',
        'name' => 'string; minLen: 3'
    ])]
    public function removeItem(int $id) {
        // ...
    }

    // expects an integer 'id' with redirection to a specific URL,
    // and storing received POST data in a flash variable
    #[TµCheckPost(
        ['id' => 'int'],
        redirect: '/path/to/error',
        flashVar: 'postErr',
    )]
    public function defineItem(int $id, mixed $value) {
        // ...
    }

    // POST parameters must validate the contract named "itemData" in
    // the configuration file, defined as follows:
    // 'validationTypes' => [
    //     'itemData' => [
    //         'code'         => 'ean',
    //         'dateCreation' => 'email; mask: @mydomain.com$',
    //         'name'         => 'string; minLen: 2',
    //     ]
    // ]
    #[TµCheckPost('itemData')]
    public function updateItem(int $itemId) {
        // ...
    }
}

---

5Files

5.1Files: overview

This attribute validates files received by a controller or an action.
It is a wrapper around the validateFiles() method of the Request object.

---

5.2Files: specific parameters

• $contract : (array) Associative array whose keys are file names and whose values are validation contracts.
• $flashVar : (string) Name of the flash variable that will contain a copy of the data received in the $_FILES superglobal if the user is redirected.

---

5.3Files: examples

use \Temma\Attributes\Check\Files as TµCheckFiles;

class Actions extends \Temma\Web\Controller {
    // this action expects a file "id_card" (no further constraints)
    #[TµCheckFiles(['id_card'])]
    public function uploadId() {
        // ...
    }

    // expects a "picto" file (GIF or PNG image) and an optional "avatar" file (PDF or image)
    #[TµCheckFiles([
        'picto'   => 'binary; mime: image/gif, image/png',
        'avatar?' => 'binary; mime: application/pdf, image'
    ])]
    public function createUser() {
        // ...
    }
}

---

6Payload

6.1Payload: overview

This attribute validates the request body content ("payload") received by a controller or an action.
It is a wrapper around the validatePayload() method of the Request object.

---

6.2Payload: specific parameters

• $contract : (string|array) Name of the contract defined in the configuration file (see documentation), or name of the validation object, or validation contract.
• $flashVar : (string) Name of the flash variable that will contain the boolean value true if the user is redirected.

---

5.3Payload: examples

use \Temma\Attributes\Check\Payload as TµCheckPayload;

class Actions extends \Temma\Web\Controller {
    // this action expects a payload containing a JSON stream (no further constraints)
    #[TµCheckPayload('json')]
    public function getStream() {
        // ...
    }

    // expects a JSON stream containing a list of integers
    #[TµCheckPayload([
        'type'     => 'json',
        'contract' => 'list; contract: int'
    ])]
    public function removeItems() {
        // ...
    }

    // expects a base64-encoded image
    #[TµCheckPayload('base64; mime: image')]
    public function uploadAvatar(int $id) {
        // ...
    }

    // expects a JSON stream containing an associative array
    // with defined and typed keys, using strict validation,
    // and defining a redirection URL
    #[TµCheckPayload(
        [
            'type'     => 'json',
            'contract' => [
                'type' => 'assoc',
                'keys' => [
                    'id'   => 'int',
                    'name' => 'string',
                    'role' => 'enum; values: user, member, admin',
                ],
            ],
        ],
        redirect: '/path/to/error',
        flashVar: 'postErr',
    )]
    public function uploadUserList() {
        // ...
    }

    // the payload must validate the contract named "internalUserJson" in
    // the configuration file, defined as follows:
    // 'validationTypes' => [
    //     'internalUserJson' => [
    //         'type'     => 'json',
    //         'contract' => [
    //             'type' => 'assoc',
    //             'keys' => [
    //                 'login' => 'string; minLen: 2',
    //                 'email' => 'email; mask: @mydomain.com$',
    //                 'name'  => 'string; minLen: 2',
    //             ]
    //         ]
    //     ]
    // ]
    #[TµCheckPayload('internalUserJson')]
    public function updateUserData(int $userId) {
        // ...
    }
}