Atributos Check

---

1Resumen

1.1Atributos de validación

Temma ofrece varios atributos usados para validar los datos entrantes:

• \Temma\Attributes\Check\Params: Valida los parámetros presentes en la URL.
• \Temma\Attributes\Check\Get: Valida los datos recibidos como parámetros GET.
• \Temma\Attributes\Check\Post: Valida los datos recibidos como parámetros POST.
• \Temma\Attributes\Check\Files: Valida los archivos subidos.
• \Temma\Attributes\Check\Payload: Valida los datos enviados en el cuerpo de la petición.

Estos atributos son wrappers que llaman a los métodos validateParams(), validateInput(), validatePayload() y validateFiles() del objeto Request. Las validaciones se basan en contratos con el formato esperado por el objeto DataFilter.

También existe un atributo para validar los datos salientes:

• \Temma\Attributes\Check\Output: Define un contrato de validación para los datos de salida, usado por la vista.

Este atributo llama al método setValidationContract() del objeto Response.

---

1.2Parámetros comunes

Algunos parámetros son comunes a todos estos atributos (excepto Output):

• $strict: (bool) Activa el modo de validación estricta (false por defecto).
• $redirect: (string) URL a la que redirigir al usuario si los datos no son válidos.
• $redirectVar: (string) Nombre de la variable de template que contiene la URL de redirección.
• $redirectReferer: (bool) true por defecto. Si es true y $redirect y $redirectVar están vacíos, se usa la cabecera HTTP REFERER como URL de redirección.
• $flashVar : (string) Nombre de la variable flash que contendrá información en caso de redirección ('form' por defecto). El contenido de la variable flash depende del atributo usado (ver más abajo).
  El valor por defecto 'form' hace que los datos recibidos estén disponibles en una variable de sesión flash llamada __form.
• $dataVar : (?string) Nombre de la variable de template que contendrá los datos validados/filtrados por el DataFilter. Esto permite recuperar directamente los datos procesados, evitando operaciones redundantes (por ejemplo, decodificar un flujo JSON, o detectar el tipo MIME de datos binarios). null por defecto (funcionalidad desactivada). No disponible para Files.

---

1.3Prioridad de redirección

Cuando los datos no son válidos, el atributo puede redirigir al usuario a otra página.
Para determinar la URL de redirección, se aplica el siguiente orden de prioridad:

1. Si el parámetro $redirect está definido, se usa.
2. Si el parámetro $redirectVar está definido y contiene el nombre de una variable de template existente y no vacía, se usa su valor.
3. Si el parámetro $redirectReferer está definido como true, y la cabecera HTTP Referer existe y no está vacía, se usa.
4. Si el archivo etc/temma.php contiene una configuración extendida x-security, y esta contiene una clave redirect, se usa su valor.

Si no se encuentra ninguna URL de redirección, se devuelve un error HTTP 403 (Forbidden).

---

2Params

2.1Params: resumen

Este atributo valida los parámetros recibidos por una acción (o por todas las acciones de un controlador).
Es un wrapper sobre el método validateParams() del objeto Request.

---

2.2Params: parámetros específicos

• $contract : (string|array) Nombre del contrato definido en el archivo de configuración (ver documentación), o nombre de un objeto de validación, o lista de contratos (un contrato por parámetro).
• $flashVar : (string) Nombre de la variable flash que contendrá una copia de los parámetros recibidos si el usuario es redirigido.

---

2.3Params: ejemplos

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

/*
 * Todas las acciones del controlador deben tener un parámetro de tipo "int"
 * y un parámetro de tipo "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 {
    // esta acción espera un parámetro entero positivo
    // y una cadena de 12 caracteres o menos
    #[TµCheckParams(['int; min: 0', 'string; maxLen: 12'])]
    public function doSomething(int $i, string $s) {
        // ...
    }

    // espera un parámetro entero y una dirección de correo,
    // con el modo de validación estricta activado, permitiendo otros parámetros
    #[TµCheckParams(
        [
            'int',
            'email',
            '...'
        ],
        strict: true,
    )]
    public function action2(int $id, string $mail, float $amount, string $name) {
        // ...
    }

    // espera un entero negativo y una cadena;
    // en caso de error, redirige a '/path/to/error';
    // los parámetros recibidos se copian en la variable flash '__getErr'
    #[TµCheckParams(
        ['int; max: 0', 'string'],
        redirect: '/path/to/error',
        flashVar: 'getErr',
    )]
    public function action3(int $id, string $value) {
        // ...
    }

    // espera un entero positivo; en caso de error, redirige a la URL
    // contenida en la variable de template 'errorPage';
    // los parámetros recibidos se copian en la variable flash
    // por defecto '__form'
    #[TµCheckParams(
        ['int; min: 1'],
        redirectVar: 'errorPage',
    )]
    public function action4(int $id) {
        // ...
    }

    // los parámetros deben validar el contrato llamado "deleteUserParameters"
    // en el archivo de configuración, definido así:
    // '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) {
        // ...
    }

    // espera un entero positivo y una cadena;
    // los datos validados se guardan en la variable de template 'params'
    #[TµCheckParams(
        ['int; min: 1', 'string; maxLen: 50'],
        dataVar: 'params',
    )]
    public function action6(int $id, string $name) {
        // $this['params'] contiene los parámetros validados/filtrados
    }
}

---

3Get

3.1Get: resumen

Este atributo valida los parámetros GET recibidos por un controlador o una acción.
Es un wrapper sobre el método validateInput() del objeto Request.

---

3.2Get: parámetros específicos

• $contract : (string|array) Nombre del contrato definido en el archivo de configuración (ver documentación), o nombre de un objeto de validación, o array asociativo cuyas claves son los nombres de los parámetros GET, y cuyos valores son los contratos de validación. Una entrada con una clave numérica y un valor de tipo cadena es una forma abreviada para un nombre de parámetro sin contrato de validación (['name'] es equivalente a ['name' => null]).
• $flashVar : (string) Nombre de la variable flash que contendrá una copia de los datos GET recibidos si el usuario es redirigido.

---

3.3Get: ejemplos

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

/*
 * Todas las acciones del controlador deben recibir los parámetros GET
 * "id" (tipo int) y "mail" (tipo 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 {
    // esta acción espera un parámetro GET "id" (sin especificar el tipo)
    #[TµCheckGet(['id'])]
    public function getList() {
        // ...
    }

    // espera un parámetro "id" y un parámetro "name" (cadena de 3 caracteres mínimo)
    // con el modo de validación estricta activado, permitiendo otros parámetros
    #[TµCheckGet(
        [
            'id',
            'name' => 'string; minLen: 3; maxLen: 20',
            '...'
        ],
        strict: true,
    )]
    public function removeItem(int $id) {
        // ...
    }

    // espera un 'id' entero y una cadena 'name' opcional;
    // en caso de error, redirige a '/path/to/error';
    // los datos GET recibidos se copian en la variable flash '__getErr'
    #[TµCheckGet(
        [
            'id'    => 'int',
            'name?' => 'string',
        ],
        redirect: '/path/to/error',
        flashVar: 'getErr',
    )]
    public function defineItem(int $id, mixed $value) {
        // ...
    }

    // espera un 'id' entero; en caso de error, no se usa el referer HTTP;
    // la redirección va a la URL definida en la configuración
    // (x-security.redirect);
    // los datos recibidos se copian en la variable flash por defecto '__form'
    #[TµCheckGet(
        ['id' => 'int'],
        redirectReferer: false,
    )]
    public function showItem(int $id) {
        // ...
    }

    // los parámetros GET deben validar el contrato llamado "internalUserData" en
    // el archivo de configuración, definido así:
    // 'validationTypes' => [
    //     'internalUserData' => [
    //         'login' => 'string; minLen: 2',
    //         'email' => 'email; mask: @mydomain.com$',
    //         'name'  => 'string; minLen: 2',
    //     ]
    // ]
    #[TµCheckGet('internalUserData')]
    public function updateUser(int $userId) {
        // ...
    }

    // espera un parámetro 'id' (entero);
    // los datos GET validados se guardan en la variable de template 'getData'
    #[TµCheckGet(
        ['id' => 'int; min: 1'],
        dataVar: 'getData',
    )]
    public function getItem() {
        // $this['getData'] contiene los datos GET validados/filtrados
    }
}

---

4Post

4.1Post: resumen

Este atributo valida los parámetros POST recibidos por un controlador o una acción.
Es un wrapper sobre el método validateInput() del objeto Request.

---

4.2Post: parámetros específicos

• $contract : (string|array) Nombre del contrato definido en el archivo de configuración (ver documentación), o nombre de un objeto de validación, o array asociativo cuyas claves son los nombres de los parámetros POST, y cuyos valores son los contratos de validación. Una entrada con una clave numérica y un valor de tipo cadena es una forma abreviada para un nombre de parámetro sin contrato de validación (['name'] es equivalente a ['name' => null]).
• $flashVar : (string) Nombre de la variable flash que contendrá una copia de los datos POST recibidos si el usuario es redirigido.

---

4.3Post: ejemplos

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

/*
 * Todas las acciones del controlador deben recibir los parámetros POST
 * "id" (tipo int) y "mail" (tipo 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 {
    // esta acción espera un parámetro POST "id" (sin especificar el tipo)
    #[TµCheckPost(['id'])]
    public function getList() {
        // ...
    }

    // espera un parámetro "id" y un parámetro "name" (cadena de 3 caracteres mínimo)
    #[TµCheckPost([
        'id',
        'name' => 'string; minLen: 3'
    ])]
    public function removeItem(int $id) {
        // ...
    }

    // espera un 'id' entero; en caso de error, redirige a '/path/to/error';
    // los datos POST recibidos se copian en la variable flash '__postErr'
    #[TµCheckPost(
        ['id' => 'int'],
        redirect: '/path/to/error',
        flashVar: 'postErr',
    )]
    public function defineItem(int $id, mixed $value) {
        // ...
    }

    // espera un 'id' entero y una cadena 'name';
    // en caso de error, redirige a la URL contenida en la variable
    // de template 'formErrorUrl'; no se define ninguna variable flash
    #[TµCheckPost(
        [
            'id'   => 'int',
            'name' => 'string',
        ],
        redirectVar: 'formErrorUrl',
        flashVar: null,
    )]
    public function createItem(int $id, string $name) {
        // ...
    }

    // los parámetros POST deben validar el contrato llamado "itemData" en
    // el archivo de configuración, definido así:
    // 'validationTypes' => [
    //     'itemData' => [
    //         'code'         => 'ean',
    //         'dateCreation' => 'email; mask: @mydomain.com$',
    //         'name'         => 'string; minLen: 2',
    //     ]
    // ]
    #[TµCheckPost('itemData')]
    public function updateItem(int $itemId) {
        // ...
    }

    // espera los parámetros POST 'email' y 'name';
    // los datos POST validados se guardan en la variable de template 'postData'
    #[TµCheckPost(
        [
            'email' => 'email',
            'name'  => 'string; minLen: 2',
        ],
        dataVar: 'postData',
    )]
    public function createUser() {
        // $this['postData'] contiene los datos POST validados/filtrados
    }
}

---

5Files

5.1Files: resumen

Este atributo valida los archivos recibidos por un controlador o una acción.
Es un wrapper sobre el método validateFiles() del objeto Request.

---

5.2Files: parámetros específicos

• $contract : (array) Array asociativo cuyas claves son los nombres de los archivos, y cuyos valores son los contratos de validación. Una entrada con una clave numérica y un valor de tipo cadena es una forma abreviada para un nombre de archivo sin contrato de validación: solo se comprueba la presencia del archivo, y su contenido no se lee (['id_card'] es equivalente a ['id_card' => null]).
• $flashVar : (string) Nombre de la variable flash que contendrá una copia de los datos recibidos en la superglobal $_FILES si el usuario es redirigido.

---

5.3Files: ejemplos

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

class Actions extends \Temma\Web\Controller {
    // esta acción espera un archivo "id_card" (sin más restricciones)
    // (forma abreviada, equivalente a ['id_card' => null])
    #[TµCheckFiles(['id_card'])]
    public function uploadId() {
        // ...
    }

    // espera un archivo "picto" (imagen GIF o PNG) y un archivo opcional "avatar" (PDF o imagen)
    #[TµCheckFiles([
        'picto'   => 'binary; mime: image/gif, image/png',
        'avatar?' => 'binary; mime: application/pdf, image'
    ])]
    public function createUser() {
        // ...
    }
}

---

6Payload

6.1Payload: resumen

Este atributo valida el contenido del cuerpo de la petición ("payload") recibido por un controlador o una acción.
Es un wrapper sobre el método validatePayload() del objeto Request.

---

6.2Payload: parámetros específicos

• $contract : (string|array) Nombre del contrato definido en el archivo de configuración (ver documentación), o nombre de un objeto de validación, o contrato de validación.
• $flashVar : (string) Nombre de la variable flash que contendrá el valor booleano true si el usuario es redirigido.

---

6.3Payload: ejemplos

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

class Actions extends \Temma\Web\Controller {
    // esta acción espera un payload que contiene un flujo JSON (sin más restricciones)
    #[TµCheckPayload('json')]
    public function getStream() {
        // ...
    }

    // espera un flujo JSON que contiene una lista de enteros
    #[TµCheckPayload([
        'type'     => 'json',
        'contract' => 'list; contract: int'
    ])]
    public function removeItems() {
        // ...
    }

    // espera una imagen codificada en base64
    #[TµCheckPayload('base64; mime: image')]
    public function uploadAvatar(int $id) {
        // ...
    }

    // espera un flujo JSON que contiene un array asociativo
    // con claves definidas y tipadas, con validación estricta;
    // en caso de error, redirige a '/path/to/error';
    // la variable flash '__postErr' se define como 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() {
        // ...
    }

    // el payload debe validar el contrato llamado "internalUserJson" en
    // el archivo de configuración, definido así:
    // '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) {
        // ...
    }

    // espera un flujo JSON que contiene un array asociativo;
    // los datos validados se guardan en la variable de template 'jsonData'
    #[TµCheckPayload(
        [
            'type'     => 'json',
            'contract' => [
                'type' => 'assoc',
                'keys' => [
                    'id'   => 'int',
                    'name' => 'string',
                ],
            ],
        ],
        dataVar: 'jsonData',
    )]
    public function importData() {
        // $this['jsonData'] contiene los datos JSON decodificados y validados
    }
}

---

7Output

7.1Output: resumen

Este atributo define un contrato de validación para los datos de salida (variables de template) de un controlador o una acción.
Es un wrapper sobre el método setValidationContract() del objeto Response. El contrato definido puede usarlo la vista para validar los datos antes de enviarlos al navegador.

A diferencia de los otros atributos Check, este atributo no admite los parámetros comunes ($strict, $redirect, $redirectVar, $flashVar).

---

7.2Output: parámetros específicos

• $contract : (null|string|array) Nombre del contrato definido en el archivo de configuración (ver documentación), o nombre de un objeto de validación, o contrato de validación (ver el objeto DataFilter), o null para eliminar un contrato definido previamente.

---

7.3Output: ejemplos

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

/*
 * Todas las acciones del controlador deben proporcionar una variable
 * de template "name" (string) y una 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 {
    // comprueba que la variable de template "id" es un entero
    // entre 5 y 128, validado de forma estricta
    #[TµCheckOutput(['id' => '=int; min: 5; max: 128'])]
    public function showItem() {
        // ...
    }

    // comprueba una variable "name" (string), una variable "mail" (email),
    // y una variable opcional "balance" (float)
    #[TµCheckOutput([
        'name'     => 'string',
        'mail'     => 'email',
        'balance?' => 'float',
    ])]
    public function showUser() {
        // ...
    }

    // los datos de salida deben validar el contrato llamado "userData"
    // en el archivo de configuración, definido así:
    // 'validationTypes' => [
    //     'userData' => [
    //         'id'    => 'int',
    //         'login' => 'string; minLen: 2',
    //         'email' => 'email',
    //     ]
    // ]
    #[TµCheckOutput('userData')]
    public function getUser(int $userId) {
        // ...
    }
}