Atributos Check

---

1Visão geral

1.1Atributos de validação

O Temma fornece vários atributos usados para validar dados recebidos:

• \Temma\Attributes\Check\Params: Valida os parâmetros presentes na URL.
• \Temma\Attributes\Check\Get: Valida os dados recebidos como parâmetros GET.
• \Temma\Attributes\Check\Post: Valida os dados recebidos como parâmetros POST.
• \Temma\Attributes\Check\Files: Valida os arquivos enviados.
• \Temma\Attributes\Check\Payload: Valida os dados enviados no corpo da requisição.

Esses atributos são wrappers que chamam os métodos validateParams(), validateInput(), validatePayload() e validateFiles() do objeto Request. As validações são baseadas em contratos no formato esperado pelo objeto DataFilter.

Também existe um atributo para validar dados de saída:

• \Temma\Attributes\Check\Output: Define um contrato de validação para os dados de saída, usado pela visão.

Este atributo chama o método setValidationContract() do objeto Response.

---

1.2Parâmetros comuns

Alguns parâmetros são comuns a todos esses atributos (exceto Output):

• $strict: (bool) Ativa o modo de validação estrita (false por padrão).
• $redirect: (string) URL para a qual redirecionar o usuário se os dados não forem válidos.
• $redirectVar: (string) Nome da variável de template contendo a URL de redirecionamento.
• $redirectReferer: (bool) true por padrão. Se true e $redirect e $redirectVar estiverem vazios, o cabeçalho HTTP REFERER é usado como URL de redirecionamento.
• $flashVar : (string) Nome da variável flash que conterá informações em caso de redirecionamento ('form' por padrão). O conteúdo da variável flash depende do atributo usado (veja abaixo).
  O valor padrão 'form' significa que os dados recebidos estão disponíveis em uma variável de sessão flash chamada __form.
• $dataVar : (?string) Nome da variável de template que conterá os dados validados/filtrados pelo DataFilter. Isso permite recuperar os dados processados diretamente, evitando operações redundantes (por exemplo, decodificar um fluxo JSON, ou detectar o tipo MIME de dados binários). null por padrão (funcionalidade desativada). Não disponível para Files.

---

1.3Prioridade de redirecionamento

Quando os dados não são válidos, o atributo pode redirecionar o usuário para outra página.
Para determinar a URL de redirecionamento, a seguinte ordem de prioridade é aplicada:

1. Se o parâmetro $redirect estiver definido, ele é usado.
2. Se o parâmetro $redirectVar estiver definido e contiver o nome de uma variável de template existente e não vazia, seu valor é usado.
3. Se o parâmetro $redirectReferer estiver definido como true, e o cabeçalho HTTP Referer existir e não estiver vazio, ele é usado.
4. Se o arquivo etc/temma.php contiver uma configuração estendida x-security com uma chave redirect, seu valor é usado.

Se nenhuma URL de redirecionamento for encontrada, um erro HTTP 403 (Forbidden) é retornado.

---

2Params

2.1Params: visão geral

Este atributo valida os parâmetros recebidos por uma ação (ou por todas as ações de um controlador).
É um wrapper em torno do método validateParams() do objeto Request.

---

2.2Params: parâmetros específicos

• $contract : (string|array) Nome do contrato definido no arquivo de configuração (veja a documentação), ou nome de um objeto de validação, ou lista de contratos (um contrato por parâmetro).
• $flashVar : (string) Nome da variável flash que conterá uma cópia dos parâmetros recebidos, caso o usuário seja redirecionado.

---

2.3Params: exemplos

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

/*
 * Todas as ações do controlador devem ter um parâmetro do tipo "int"
 * e um parâmetro do 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 ação espera um parâmetro inteiro positivo
    // e uma string com até 12 caracteres
    #[TµCheckParams(['int; min: 0', 'string; maxLen: 12'])]
    public function doSomething(int $i, string $s) {
        // ...
    }

    // espera um parâmetro inteiro e um endereço de e-mail,
    // com o modo de validação estrita ativado, permitindo parâmetros adicionais
    #[TµCheckParams(
        [
            'int',
            'email',
            '...'
        ],
        strict: true,
    )]
    public function action2(int $id, string $mail, float $amount, string $name) {
        // ...
    }

    // espera um inteiro negativo e uma string;
    // em caso de erro, redireciona para '/path/to/error';
    // os parâmetros recebidos são copiados para a variável flash '__getErr'
    #[TµCheckParams(
        ['int; max: 0', 'string'],
        redirect: '/path/to/error',
        flashVar: 'getErr',
    )]
    public function action3(int $id, string $value) {
        // ...
    }

    // espera um inteiro positivo; em caso de erro, redireciona para a URL
    // contida na variável de template 'errorPage';
    // os parâmetros recebidos são copiados para a variável flash
    // padrão '__form'
    #[TµCheckParams(
        ['int; min: 1'],
        redirectVar: 'errorPage',
    )]
    public function action4(int $id) {
        // ...
    }

    // os parâmetros devem validar o contrato chamado "deleteUserParameters"
    // no arquivo de configuração, definido da seguinte forma:
    // '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 um inteiro positivo e uma string;
    // dados validados são armazenados na variável de template 'params'
    #[TµCheckParams(
        ['int; min: 1', 'string; maxLen: 50'],
        dataVar: 'params',
    )]
    public function action6(int $id, string $name) {
        // $this['params'] contém os parâmetros validados/filtrados
    }
}

---

3Get

3.1Get: visão geral

Este atributo valida os parâmetros GET recebidos por um controlador ou uma ação.
É um wrapper em torno do método validateInput() do objeto Request.

---

3.2Get: parâmetros específicos

• $contract : (string|array) Nome do contrato definido no arquivo de configuração (veja a documentação), ou nome de um objeto de validação, ou array associativo cujas chaves são os nomes dos parâmetros GET, e cujos valores são os contratos de validação.
• $flashVar : (string) Nome da variável flash que conterá uma cópia dos dados GET recebidos, caso o usuário seja redirecionado.

---

3.3Get: exemplos

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

/*
 * Todas as ações do controlador devem receber os parâmetros GET
 * "id" (tipo int) e "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 ação espera um parâmetro GET "id" (sem especificar o tipo)
    #[TµCheckGet(['id'])]
    public function getList() {
        // ...
    }

    // espera um parâmetro "id" e um parâmetro "name" (string com no mínimo 3 caracteres)
    // com o modo de validação estrita ativado, permitindo parâmetros adicionais
    #[TµCheckGet(
        [
            'id',
            'name' => 'string; minLen: 3; maxLen: 20',
            '...'
        ],
        strict: true,
    )]
    public function removeItem(int $id) {
        // ...
    }

    // espera um 'id' inteiro e uma 'name' string opcional;
    // em caso de erro, redireciona para '/path/to/error';
    // os dados GET recebidos são copiados para a variável flash '__getErr'
    #[TµCheckGet(
        [
            'id'    => 'int',
            'name?' => 'string',
        ],
        redirect: '/path/to/error',
        flashVar: 'getErr',
    )]
    public function defineItem(int $id, mixed $value) {
        // ...
    }

    // espera um 'id' inteiro; em caso de erro, o referer HTTP não é usado;
    // o redirecionamento vai para a URL definida na configuração
    // (x-security.redirect);
    // os dados recebidos são copiados para a variável flash padrão '__form'
    #[TµCheckGet(
        ['id' => 'int'],
        redirectReferer: false,
    )]
    public function showItem(int $id) {
        // ...
    }

    // os parâmetros GET devem validar o contrato chamado "internalUserData" no
    // arquivo de configuração, definido da seguinte forma:
    // 'validationTypes' => [
    //     'internalUserData' => [
    //         'login' => 'string; minLen: 2',
    //         'email' => 'email; mask: @mydomain.com$',
    //         'name'  => 'string; minLen: 2',
    //     ]
    // ]
    #[TµCheckGet('internalUserData')]
    public function updateUser(int $userId) {
        // ...
    }

    // espera um parâmetro 'id' (inteiro);
    // dados GET validados são armazenados na variável de template 'getData'
    #[TµCheckGet(
        ['id' => 'int; min: 1'],
        dataVar: 'getData',
    )]
    public function getItem() {
        // $this['getData'] contém os dados GET validados/filtrados
    }
}

---

4Post

4.1Post: visão geral

Este atributo valida os parâmetros POST recebidos por um controlador ou uma ação.
É um wrapper em torno do método validateInput() do objeto Request.

---

4.2Post: parâmetros específicos

• $contract : (string|array) Nome do contrato definido no arquivo de configuração (veja a documentação), ou nome de um objeto de validação, ou array associativo cujas chaves são os nomes dos parâmetros POST, e cujos valores são os contratos de validação.
• $flashVar : (string) Nome da variável flash que conterá uma cópia dos dados POST recebidos, caso o usuário seja redirecionado.

---

4.3Post: exemplos

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

/*
 * Todas as ações do controlador devem receber os parâmetros POST
 * "id" (tipo int) e "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 ação espera um parâmetro POST "id" (sem especificar o tipo)
    #[TµCheckPost(['id'])]
    public function getList() {
        // ...
    }

    // espera um parâmetro "id" e um parâmetro "name" (string com no mínimo 3 caracteres)
    #[TµCheckPost([
        'id',
        'name' => 'string; minLen: 3'
    ])]
    public function removeItem(int $id) {
        // ...
    }

    // espera um 'id' inteiro; em caso de erro, redireciona para '/path/to/error';
    // os dados POST recebidos são copiados para a variável flash '__postErr'
    #[TµCheckPost(
        ['id' => 'int'],
        redirect: '/path/to/error',
        flashVar: 'postErr',
    )]
    public function defineItem(int $id, mixed $value) {
        // ...
    }

    // espera um 'id' inteiro e uma string 'name';
    // em caso de erro, redireciona para a URL contida na
    // variável de template 'formErrorUrl'; nenhuma variável flash é definida
    #[TµCheckPost(
        [
            'id'   => 'int',
            'name' => 'string',
        ],
        redirectVar: 'formErrorUrl',
        flashVar: null,
    )]
    public function createItem(int $id, string $name) {
        // ...
    }

    // os parâmetros POST devem validar o contrato chamado "itemData" no
    // arquivo de configuração, definido da seguinte forma:
    // 'validationTypes' => [
    //     'itemData' => [
    //         'code'         => 'ean',
    //         'dateCreation' => 'email; mask: @mydomain.com$',
    //         'name'         => 'string; minLen: 2',
    //     ]
    // ]
    #[TµCheckPost('itemData')]
    public function updateItem(int $itemId) {
        // ...
    }

    // espera os parâmetros POST 'email' e 'name';
    // dados POST validados são armazenados na variável de template 'postData'
    #[TµCheckPost(
        [
            'email' => 'email',
            'name'  => 'string; minLen: 2',
        ],
        dataVar: 'postData',
    )]
    public function createUser() {
        // $this['postData'] contém os dados POST validados/filtrados
    }
}

---

5Files

5.1Files: visão geral

Este atributo valida os arquivos recebidos por um controlador ou uma ação.
É um wrapper em torno do método validateFiles() do objeto Request.

---

5.2Files: parâmetros específicos

• $contract : (array) Array associativo cujas chaves são os nomes dos arquivos, e cujos valores são os contratos de validação.
• $flashVar : (string) Nome da variável flash que conterá uma cópia dos dados recebidos na superglobal $_FILES, caso o usuário seja redirecionado.

---

5.3Files: exemplos

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

class Actions extends \Temma\Web\Controller {
    // esta ação espera um arquivo "id_card" (sem outras restrições)
    #[TµCheckFiles(['id_card'])]
    public function uploadId() {
        // ...
    }

    // espera um arquivo "picto" (imagem GIF ou PNG) e um arquivo opcional "avatar" (PDF ou imagem)
    #[TµCheckFiles([
        'picto'   => 'binary; mime: image/gif, image/png',
        'avatar?' => 'binary; mime: application/pdf, image'
    ])]
    public function createUser() {
        // ...
    }
}

---

6Payload

6.1Payload: visão geral

Este atributo valida o conteúdo do corpo da requisição ("payload") recebido por um controlador ou uma ação.
É um wrapper em torno do método validatePayload() do objeto Request.

---

6.2Payload: parâmetros específicos

• $contract : (string|array) Nome do contrato definido no arquivo de configuração (veja a documentação), ou nome do objeto de validação, ou contrato de validação.
• $flashVar : (string) Nome da variável flash que conterá o valor booleano true, caso o usuário seja redirecionado.

---

6.3Payload: exemplos

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

class Actions extends \Temma\Web\Controller {
    // esta ação espera um payload contendo um fluxo JSON (sem outras restrições)
    #[TµCheckPayload('json')]
    public function getStream() {
        // ...
    }

    // espera um fluxo JSON contendo uma lista de inteiros
    #[TµCheckPayload([
        'type'     => 'json',
        'contract' => 'list; contract: int'
    ])]
    public function removeItems() {
        // ...
    }

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

    // espera um fluxo JSON contendo um array associativo
    // com chaves definidas e tipadas, usando validação estrita;
    // em caso de erro, redireciona para '/path/to/error';
    // a variável flash '__postErr' é definida 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() {
        // ...
    }

    // o payload deve validar o contrato chamado "internalUserJson" no
    // arquivo de configuração, definido da seguinte forma:
    // '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 um fluxo JSON contendo um array associativo;
    // dados validados são armazenados na variável de template 'jsonData'
    #[TµCheckPayload(
        [
            'type'     => 'json',
            'contract' => [
                'type' => 'assoc',
                'keys' => [
                    'id'   => 'int',
                    'name' => 'string',
                ],
            ],
        ],
        dataVar: 'jsonData',
    )]
    public function importData() {
        // $this['jsonData'] contém os dados JSON decodificados e validados
    }
}

---

7Output

7.1Output: visão geral

Este atributo define um contrato de validação para os dados de saída (variáveis de template) de um controlador ou uma ação.
É um wrapper em torno do método setValidationContract() do objeto Response. O contrato definido pode ser usado pela visão para validar os dados antes de enviá-los ao navegador.

Ao contrário dos outros atributos Check, este atributo não suporta os parâmetros comuns ($strict, $redirect, $redirectVar, $flashVar).

---

7.2Output: parâmetros específicos

• $contract : (null|string|array) Nome do contrato definido no arquivo de configuração (veja a documentação), ou nome de um objeto de validação, ou contrato de validação (veja o objeto DataFilter), ou null para remover um contrato definido anteriormente.

---

7.3Output: exemplos

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

/*
 * Todas as ações do controlador devem fornecer uma variável de template "name" (string)
 * e uma variável "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 {
    // verifica se a variável de template "id" é um inteiro
    // entre 5 e 128, com validação estrita
    #[TµCheckOutput(['=id' => 'int; min: 5; max: 128'])]
    public function showItem() {
        // ...
    }

    // verifica uma variável "name" (string), uma variável "mail" (email),
    // e uma variável opcional "balance" (float)
    #[TµCheckOutput([
        'name'     => 'string',
        'mail'     => 'email',
        'balance?' => 'float',
    ])]
    public function showUser() {
        // ...
    }

    // os dados de saída devem validar o contrato chamado "userData"
    // no arquivo de configuração, definido da seguinte forma:
    // 'validationTypes' => [
    //     'userData' => [
    //         'id'    => 'int',
    //         'login' => 'string; minLen: 2',
    //         'email' => 'email',
    //     ]
    // ]
    #[TµCheckOutput('userData')]
    public function getUser(int $userId) {
        // ...
    }
}