Attributs Check

---

1Présentation

1.1Attributs de validation

Temma propose plusieurs attributs servant à valider les données entrantes :

• \Temma\Attributes\Check\Get : Pour valider les données reçues en paramètres GET.
• \Temma\Attributes\Check\Post : Pour valider les données reçues en paramètres POST.
• \Temma\Attributes\Check\Files : Pour valider les fichiers qui doivent être uploadés.
• \Temma\Attributes\Check\Payload : Pour valider les données envoyées en corps de requêtes.

Ces attributs sont des wrappers qui appelent les méthodes validateParams(), validatePayload() et validateFiles() de l'objet Request. Les validations se basent sur des contrats au format attendu par l'objet DataFilter.

---

1.2Paramètres communs

Certains paramètres sont communs à tous ces attributs :

• $strict : (bool) Pour utiliser le mode de validation stricte (false par défaut).
• $redirect : (string) URL vers laquelle rediriger l'utilisateur si les données ne sont pas valides.
• $redirectVar : (string) Nom de la variable de template contenant l'URL vers laquelle rediriger l'utilisateur.
• $flashVar : (string) Nom de la variable flash dans laquelle les données GET reçues seront copiées si l'utilisateur est redirigé.

---

1.3Priorité de redirection

Lorsque les données ne sont pas valides, l'attribut peut rediriger l'utilisateur vers une autre page.
Pour définir l'URL vers laquelle l'utilisateur va être redirigé, l'attribut applique l'ordre de priorité suivant :

1. Si le paramètre $redirect est défini, il est utilisé.
2. Si le paramètre $redirectVar est défini, et qu'il contient le nom d'une variable de template qui existe et est non vide, le contenu de celle-ci est utilisé.
3. Si le fichier etc/temma.php contient une configuration étendue x-security, et que celle-ci contient une clé redirect, le contenu de celle-ci est utilisé.

Si aucune URL de redirection n'a été trouvée, une erreur 403 est retournée.

---

2Get

2.1Get : présentation

Cet attribut permet de valider les paramètres GET reçus par un contrôleur ou une action.
C'est un wrapper sur la méthode validateParams() de l'objet Request.

---

2.2Get : paramètre spécifique

• $parameters : (array) Tableau associatif dont les clés sont les paramètres GET, et les valeurs sont les contrats de validation.

---

2.3Get : exemples

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

/*
 * Toutes les actions du contrôleur doivent recevoir les paramètres GET
 * "id" (type int) et "mail" (type email).
 */
#[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 {
    // cette action attend un paramètre GET "id" (sans préciser le type)
    #[TµCheckGet(['id'])]
    public function getList() {
        // ...
    }

    // attend un paramètre "id" et un paramètre "name" (string de 3 caractères minimum)
    // avec une validation en mode strict, et en autorisant d'autres paramètres
    #[TµCheckGet(
        [
            'id',
            'name' => 'string; minLen: 3; maxLen: 20',
            '...'
        ],
        strict: true,
    )]
    public function removeItem(int $id) {
        // ...
    }

    // attend un entier 'id' et une chaîne 'name' optionnelle,
    // avec redirection vers une URL particulière,
    // et en enregistrant les données GET reçues dans une variable flash
    #[TµCheckGet(
        [
            'id'    => 'int',
            'name?' =>; 'string', 
        ],
        redirect: '/path/to/error',
        flashVar: 'getErr',
    )]
    public function defineItem(int $id, mixed $value) {
        // ...
    }
}

---

3Post

3.1Post : présentation

Cet attribut permet de valider les paramètres POST reçus par un contrôleur ou une action.
C'est un wrapper sur la méthode validateParams() de l'objet Request.

---

3.2Post : paramètre spécifique

• $parameters : (array) Tableau associatif dont les clés sont les paramètres POST, et les valeurs sont les contrats de validation.

---

3.3Post : exemples

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

/*
 * Toutes les actions du contrôleur doivent recevoir les paramètres POST
 * "id" (type int) et "mail" (type email).
 */
#[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 {
    // cette action attend un paramètre POST "id" (sans préciser le type)
    #[TµCheckPost(['id'])]
    public function getList() {
        // ...
    }

    // attend un paramètre "id" et un paramètre "name" (string de 3 caractères minimum)
    #[TµCheckPost([
        'id',
        'name' => 'string; minLen: 3'
    ])]
    public function removeItem(int $id) {
        // ...
    }

    // attend un entier 'id' avec redirection vers une URL particulière,
    // et en enregistrant les données POST reçues dans une variable flash
    #[TµCheckPost(
        ['id' => 'int'],
        redirect: '/path/to/error',
        flashVar: 'postErr',
    )]
    public function defineItem(int $id, mixed $value) {
        // ...
    }
}

---

4Files

4.1Files : présentation

Cet attribut permet de valider les fichiers reçus par un contrôleur ou une action.
C'est un wrapper sur la méthode validateFiles() de l'objet Request.

---

4.2Files : paramètre spécifique

• $contract : (array) Tableau associatif dont les clés sont les noms des fichiers, et les valeurs sont les contrats de validation.

---

4.3Files : exemples

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

class Actions extends \Temma\Web\Controller {
    // cette action attend un fichier "id_card" (sans autre précision)
    #[TµCheckFiles(['id_card'])]
    public function uploadId() {
        // ...
    }

    // attend un fichier "picto" (image GIF ou PNG) et un fichier optionnel "avatar" (PDF ou image)
    #[TµCheckFiles([
        'picto'   => 'binary; mime: image/gif, image/png',
        'avatar?' => 'binary; mime: application/pdf, image'
    ])]
    public function createUser() {
        // ...
    }
}

---

5Payload

5.1Payload : présentation

Cet attribut permet de valider le contenu du corps de la requête (le "payload") reçu par un contrôleur ou une action.
C'est un wrapper sur la méthode validatePayload() de l'objet Request.

---

5.2Payload : paramètre spécifique

• $contract : (array) Contrat de validation.

---

5.3Payload : exemples

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

class Actions extends \Temma\Web\Controller {
    // cette action attend un payload contenant un flux JSON (sans plus de précision)
    #[TµCheckPayload('json')]
    public function getStream() {
        // ...
    }

    // attend un flux JSON contenant une liste d'entiers
    #[TµCheckPayload([
        'type'     => 'json',
        'contract' => 'list; contract: int'
    ])]
    public function removeItems() {
        // ...
    }

    // attend une image encodée en base 64
    #[TµCheckPayload('base64; mime: image')]
    public function uploadAvatar(int $id) {
        // ...
    }

    // attend un flux json contenant un tableau associatif
    // dont les clés sont définies et typées, avec validation stricte,
    // et en définissant l'URL de redirection
    #[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() {
        // ...
    }
}