Check attributes

---

1Overview

1.1Validation attributes

Temma provides several attributes used to validate incoming data:

• \Temma\Attributes\Check\Get: To validate data received through GET parameters.
• \Temma\Attributes\Check\Post: To validate data received through POST parameters.
• \Temma\Attributes\Check\Files: To validate uploaded files.
• \Temma\Attributes\Check\Payload: To validate data sent in the request body.

These attributes are wrappers that call the validateParams(), 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 in which received data will be stored if the user is redirected.

---

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.

---

2Get

2.1Get: overview

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

---

2.2Get: specific parameter

• $parameters: (array) Associative array where keys are GET parameters and values are validation contracts.

---

2.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) {
        // ...
    }
}

---

3Post

3.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.

---

3.2Post: specific parameter

• $parameters: (array) Associative array where keys are POST parameters and values are validation contracts.

---

3.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) {
        // ...
    }
}

---

4Files

4.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.

---

4.2Files: specific parameter

• $contract: (array) Associative array where keys are file names and values are validation contracts.

---

4.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() {
        // ...
    }
}

---

5Payload

5.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.

---

5.2Payload: specific parameter

• $contract: (array) Validation contract.

---

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() {
        // ...
    }
}