Attributs Check

---

1Présentation

1.1Attributs de validation

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

• \Temma\Attributes\Check\Params : Pour valider les paramètres présents dans l'URL.
• \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 dans le corps de la requête.

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

Il existe aussi un attribut pour la validation des données sortantes :

• \Temma\Attributes\Check\Output : Pour définir un contrat de validation des données de sortie, utilisé par la vue.

Cet attribut appelle la méthode setValidationContract() de l'objet Response.

---

1.2Paramètres communs

Certains paramètres sont communs à tous ces attributs (sauf Output) :

• $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.
• $redirectReferer : (bool) true par défaut. Si true et que $redirect et $redirectVar sont vides, l'en-tête HTTP REFERER est utilisé comme URL de redirection.
• $flashVar : (string) Nom de la variable flash qui contiendra des informations en cas de redirection ('form' par défaut). Le contenu de la variable flash dépend de l'attribut utilisé (voir plus bas).
  La valeur par défaut 'form' fait que les données reçues sont disponibles dans une variable de session flash nommée __form.

---

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 paramètre $redirectReferer est à true, et que l'en-tête HTTP Referer existe et est non vide, il est utilisé.
4. 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 HTTP 403 (Forbidden) est retournée.

---

2Params

2.1Params : présentation

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

---

2.2Params : paramètres spécifiques

• $contract : (string|array) Nom du contrat défini dans le fichier de configuration (voir documentation), ou nom de l'objet de validation, ou liste de contrats (un contrat par paramètre).
• $flashVar : (string) Nom de la variable flash qui contiendra une copie des paramètres reçus si l'utilisateur est redirigé.

---

2.3Params : exemples

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

/*
 * Toutes les actions du contrôleur doivent avoir un paramètre de type "int"
 * et un paramètre de 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 {
    // cette action attend un paramètre entier positif
    // et une chaîne de 12 caractères ou moins
    #[TµCheckParams(['int; min: 0', 'string; maxLen: 12'])]
    public function doSomething(int $i, string $s) {
        // ...
    }

    // attend un paramètre entier et une adresse mail,
    // avec une validation en mode strict, et en autorisant d'autres paramètres
    #[TµCheckParams(
        [
            'int',
            'email',
            '...'
        ],
        strict: true,
    )]
    public function action2(int $id, string $mail, float $amount, string $name) {
        // ...
    }

    // attend un entier négatif et une chaîne ;
    // en cas d'erreur, redirige vers '/path/to/error' ;
    // les paramètres reçus sont copiés dans la variable flash '__getErr'
    #[TµCheckParams(
        ['int; max: 0', 'string'],
        redirect: '/path/to/error',
        flashVar: 'getErr',
    )]
    public function action3(int $id, string $value) {
        // ...
    }

    // attend un entier positif ; en cas d'erreur, redirige vers l'URL
    // contenue dans la variable de template 'errorPage' ;
    // les paramètres reçus sont copiés dans la variable flash
    // par défaut '__form'
    #[TµCheckParams(
        ['int; min: 1'],
        redirectVar: 'errorPage',
    )]
    public function action4(int $id) {
        // ...
    }

    // les paramètres doivent valider le contrat nommé "deleteUserParameters"
    // dans le fichier de configuration, et qui a été défini ainsi :
    // '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 : 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 validateInput() de l'objet Request.

---

3.2Get : paramètres spécifiques

• $contract : (string|array) Nom du contrat défini dans le fichier de configuration (voir documentation), ou nom de l'objet de validation, ou tableau associatif dont les clés sont les paramètres GET, et les valeurs sont les contrats de validation.
• $flashVar : (string) Nom de la variable flash qui contiendra une copie des données GET reçues si l'utilisateur est redirigé.

---

3.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 ;
    // en cas d'erreur, redirige vers '/path/to/error' ;
    // les données GET reçues sont copiées dans la variable flash '__getErr'
    #[TµCheckGet(
        [
            'id'    => 'int',
            'name?' => 'string',
        ],
        redirect: '/path/to/error',
        flashVar: 'getErr',
    )]
    public function defineItem(int $id, mixed $value) {
        // ...
    }

    // attend un entier 'id' ; en cas d'erreur, le referer HTTP n'est pas
    // utilisé ; la redirection se fait vers l'URL définie dans la
    // configuration (x-security.redirect) ;
    // les données reçues sont copiées dans la variable flash
    // par défaut '__form'
    #[TµCheckGet(
        ['id' => 'int'],
        redirectReferer: false,
    )]
    public function showItem(int $id) {
        // ...
    }

    // les paramètres GET doivent valider le contrat nommé "internalUserData" dans
    // le fichier de configuration, et qui a été défini ainsi :
    // '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 : 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 validateInput() de l'objet Request.

---

4.2Post : paramètres spécifiques

• $contract : (string|array) Nom du contrat défini dans le fichier de configuration (voir documentation), ou nom de l'objet de validation, ou tableau associatif dont les clés sont les paramètres POST, et les valeurs sont les contrats de validation.
• $flashVar : (string) Nom de la variable flash qui contiendra une copie des données POST reçues si l'utilisateur est redirigé.

---

4.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' ; en cas d'erreur, redirige vers '/path/to/error' ;
    // les données POST reçues sont copiées dans la variable flash '__postErr'
    #[TµCheckPost(
        ['id' => 'int'],
        redirect: '/path/to/error',
        flashVar: 'postErr',
    )]
    public function defineItem(int $id, mixed $value) {
        // ...
    }

    // attend un entier 'id' et une chaîne 'name' ;
    // en cas d'erreur, redirige vers l'URL contenue dans la variable
    // de template 'formErrorUrl' ; aucune variable flash n'est remplie
    #[TµCheckPost(
        [
            'id'   => 'int',
            'name' => 'string',
        ],
        redirectVar: 'formErrorUrl',
        flashVar: null,
    )]
    public function createItem(int $id, string $name) {
        // ...
    }

    // les paramètres POST doivent valider le contrat nommé "itemData" dans
    // le fichier de configuration, et qui a été défini ainsi :
    // 'validationTypes' => [
    //     'itemData' => [
    //         'code'         => 'ean',
    //         'dateCreation' => 'email; mask: @mydomain.com$',
    //         'name'         => 'string; minLen: 2',
    //     ]
    // ]
    #[TµCheckPost('itemData')]
    public function updateItem(int $itemId) {
        // ...
    }
}

---

5Files

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

---

5.2Files : paramètres spécifiques

• $contract : (array) Tableau associatif dont les clés sont les noms des fichiers, et les valeurs sont les contrats de validation.
• $flashVar : (string) Nom de la variable flash qui contiendra une copie des données reçues dans la superglobale $_FILES si l'utilisateur est redirigé.

---

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

---

6Payload

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

---

6.2Payload : paramètres spécifiques

• $contract : (string|array) Nom du contrat défini dans le fichier de configuration (voir documentation), ou nom de l'objet de validation, ou contrat de validation.
• $flashVar : (string) Nom de la variable flash qui contiendra la valeur booléenne true si l'utilisateur est redirigé.

---

6.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 ;
    // en cas d'erreur, redirige vers '/path/to/error' ;
    // la variable flash '__postErr' est mise à true
    #[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() {
        // ...
    }

    // le payload doit valider le contrat nommé "internalUserJson" dans
    // le fichier de configuration, et qui a été défini ainsi :
    // '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) {
        // ...
    }
}

---

7Output

7.1Output : présentation

Cet attribut permet de définir un contrat de validation des données de sortie (les variables de template) pour un contrôleur ou une action.
C'est un wrapper sur la méthode setValidationContract() de l'objet Response. Le contrat défini pourra être utilisé par la vue pour valider les données avant de les envoyer au navigateur.

Contrairement aux autres attributs Check, cet attribut ne prend pas en charge les paramètres communs ($strict, $redirect, $redirectVar, $flashVar).

---

7.2Output : paramètres spécifiques

• $contract : (null|string|array) Nom du contrat défini dans le fichier de configuration (voir documentation), ou nom de l'objet de validation, ou contrat de validation (voir l'objet DataFilter), ou null pour effacer un contrat préalablement défini.

---

7.3Output : exemples

use \Temma\Attributes\Check\Output as TµCheckOutput;

/*
 * Toutes les actions du contrôleur doivent fournir une variable
 * de template "name" (string) et une variable "mail" (email).
 */
#[TµCheckOutput([
    'name' => 'string',
    'mail' => 'email',
])]
class Actions extends \Temma\Web\Controller {
    // ...
}

use \Temma\Attributes\Check\Output as TµCheckOutput;

class Actions extends \Temma\Web\Controller {
    // vérifie que la variable de template "id" est un entier
    // entre 5 et 128, validé de manière stricte
    #[TµCheckOutput(['=id' => 'int; min: 5; max: 128'])]
    public function showItem() {
        // ...
    }

    // vérifie une variable "name" (string), une variable "mail" (email)
    // et une variable optionnelle "balance" (float)
    #[TµCheckOutput([
        'name'     => 'string',
        'mail'     => 'email',
        'balance?' => 'float',
    ])]
    public function showUser() {
        // ...
    }

    // les données de sortie doivent valider le contrat nommé "userData"
    // dans le fichier de configuration, et qui a été défini ainsi :
    // 'validationTypes' => [
    //     'userData' => [
    //         'id'    => 'int',
    //         'login' => 'string; minLen: 2',
    //         'email' => 'email',
    //     ]
    // ]
    #[TµCheckOutput('userData')]
    public function getUser(int $userId) {
        // ...
    }
}