Objetos internos

---

1Visão geral

Quando o Temma executa uma requisição, ele instancia vários objetos que são necessários para esse processamento, e os disponibiliza para os controladores e os plugins.

Esses objetos são do tipo:

• \Temma\Base\Session: gerenciamento de sessões de usuário (veja a documentação dedicada).
• \Temma\Web\Config: recuperação das informações de configuração.
• \Temma\Web\Request: recuperação e modificação dos dados que compõem a requisição.
• \Temma\Web\Response: controle de determinados parâmetros da resposta.

---

2Config

2.1Config: visão geral

Esse objeto é usado para acessar e modificar a configuração do site durante a requisição atual.

O objeto de configuração está disponível nos controladores e nos plugins ao escrever:

$this->_config

Nos outros objetos gerenciados pelo componente de injeção de dependências, o objeto de configuração é acessível ao escrever:

$this->_loader->config

---

2.2Config: atributos de leitura e escrita

• appPath : (string) caminho para a raiz do projeto
• etcPath : (string) caminho para o diretório 'etc' do projeto
• logPath : (string) caminho para o diretório 'log' do projeto
• tmpPath : (string) caminho para o diretório 'tmp' do projeto
• includesPath : (string) caminho para o diretório 'lib' do projeto
• controllersPath : (string) caminho para o diretório 'controllers' do projeto
• varPath : (string) caminho para o diretório 'var' do projeto
• webPath : (string) caminho para o diretório 'www' do projeto
• routes : (array) roteamento básico
• plugins : (array) lista de plugins
• enableSessions : (bool) indica se as sessões estão habilitadas
• rootController : (string) nome do controlador raiz
• defaultController : (string) nome do controlador padrão
• proxyController : (string) nome do controlador proxy
• defaultNamespace : (string) namespace padrão dos controladores
• defaultView : (string) nome da visão padrão
• loader : (string) nome do objeto usado como componente de injeção de dependências
• loaderAliases : (?array) array associativo contendo os aliases de nomenclatura gerenciados pelo loader
• loaderPrefixes : (?array) array associativo contendo os prefixos de nomenclatura gerenciados pelo loader
• logManager : (null|string|array) nome do(s) gerenciador(es) de log
• logLevels : (null|string|array) limites de log
• bufferingLoglevels : (null|string|array) limites de log em buffer

---

2.3Config: gerenciamento de configurações estendidas

O método xtra() é usado para ler uma configuração estendida:

// recupera toda a configuração estendida "x-user"
$conf = $this->_config->xtra('user');

// recupera a chave "login"
$login = $this->_config->xtra('user', 'login');

// recupera a chave "login", com valor padrão
$login = $this->_config->xtra('user', 'login', 'admin');

O método setXtra() é usado para definir uma chave em uma configuração estendida:

// define a chave "login" na configuração estendida "x-user"
$this->_config->setXtra('user', 'login', 'sysop');

---

3Request

3.1Request: visão geral

O gerenciamento da requisição raramente é usado nos controladores da aplicação. No entanto, pode ser útil em plugins que querem controlar o fluxo de execução alterando as características da requisição.

O objeto de requisição está disponível nos controladores e nos plugins ao escrever:

$this->_request

Nos outros objetos gerenciados pelo componente de injeção de dependências, o objeto de requisição é acessível ao escrever:

$this->_loader->request

---

3.2Request: métodos de leitura

// descobre se é uma requisição AJAX
$ajax = $this->_request->isAjax();

// recupera os formatos de dados aceitos pelo navegador
// ("text/html", "application/json", "image/png", etc.)
$formats = $this->_request->getAcceptedFormats();

// indica se um determinado formato é aceito pelo navegador
// ("text/html", "text", "image/png", "image", "*/*", "*", etc.)
$bool = $this->_request->isAcceptedFormat($format);

// recupera o path info
$pathInfo = $this->_request->getPathInfo();

// recupera o método (GET, POST...)
$method = $this->_request->getMethod();

// recupera o nome do controlador
$ctrl = $this->_request->getController();

// recupera o nome da ação
$action = $this->_request->getAction();

// recupera o número de parâmetros
$cnt = $this->_request->getParamCount();

// recupera a lista de parâmetros
$params = $this->_request->getParams();

// recupera o primeiro parâmetro
$p1 = $this->_request->getParam(0);
// recupera o 2º parâmetro, com um valor padrão
$p2 = $this->_request->getParam(1, 'toto');

// recupera o caminho a partir da raiz do site
$path = $this->_request->getSitePath();

---

3.3Request: métodos de escrita

// definição do método
$this->_request->setMethod('POST');

// definição do controlador
$this->_request->setController('user');
// recomendado: atualizar a variável de template associada
$this['CONTROLLER'] = 'user';

// definição da ação
$this->_request->setAction('list');
// recomendado: atualizar a variável de template associada
$this['ACTION'] = 'list';

// definição da lista de parâmetros
$this->_request->setParams(['toto', 'titi']);

// definição do segundo parâmetro
$this->_request->setParam(1, 'tata');

---

3.4Request: métodos de validação

O objeto Request oferece quatro métodos para validar os dados recebidos: validateParams(), validateInput(), validatePayload() e validateFiles().

As validações se baseiam em contratos no formato esperado pelo objeto DataFilter.

Esses métodos lançam uma exceção \Temma\Exceptions\Application se os dados forem inválidos. Eles lançam uma exceção \Temma\Exceptions\IO se um contrato estiver incorreto.

validateParams()

Esse método valida os parâmetros recebidos na URL.

No modo de validação não estrita (comportamento padrão), os parâmetros podem ser modificados: uma string que exceda o tamanho máximo definido será truncada, os tipos são convertidos se necessário, os parâmetros não definidos são removidos, etc.

Parâmetros:

• $contract (null|string|array): Definição do contrato de validação. Pode ser de dois tipos:
  • Uma string correspondente a um contrato de validação definido no arquivo de configuração, ou a um objeto de validação.
  • Uma lista de contratos (veja o objeto DataFilter), com um contrato por parâmetro. É possível especificar ... para indicar que os parâmetros seguintes são aceitos como estão.
• $strict (bool): Habilita o modo de validação estrita (veja o objeto DataFilter).
• &$output (mixed): Variável passada por referência que vai receber os dados de saída do DataFilter (dados validados/filtrados e metadados opcionais).

Se forem fornecidos mais parâmetros do que os definidos, e não houver uma entrada ... na lista de contratos:

• No modo não estrito, os parâmetros adicionais são removidos.
• No modo estrito, uma exceção é lançada.

Exemplos:

// valida que o primeiro parâmetro é um inteiro maior ou igual a 20
// e que o segundo é uma cor hexadecimal
$request->validateParams(['int; min: 20', 'color']);

// valida que o primeiro parâmetro é um inteiro positivo,
// que o segundo é uma enumeração, e que o terceiro é uma string
// que começa com "foo"
$request->validateParams([
    'int; min: 0',
    'enum; values: member, admin',
    'string; mask: ^foo'
]);

// valida que o primeiro parâmetro é um inteiro
// e que parâmetros adicionais são permitidos
$request->validateParams(['int', '...']);

// valida um contrato chamado "userUpdateParams" definido na configuração,
// e declarado da seguinte forma:
// 'validationTypes' => [
//     'userUpdateParams' => 'list; values: int, int, string'
// ]
$request->validateInput('userUpdateParams');

// valida e recupera os dados filtrados
$output = null;
$request->validateParams(['int; min: 1', 'slug'], output: $output);
// $output contém os parâmetros validados

validateInput()

Esse método valida os dados recebidos como parâmetros GET ou POST.

No modo de validação não estrita (comportamento padrão), os parâmetros GET/POST podem ser modificados: uma string que exceda o tamanho máximo definido será truncada, os tipos são convertidos se necessário, os parâmetros não definidos são removidos, etc.

Parâmetros:

• $contract (null|string|array): Definição do contrato de validação. Pode ser de dois tipos:
  • Uma string correspondente a um contrato de validação definido no arquivo de configuração, ou a um objeto de validação.
  • Array associativo cujas chaves são os parâmetros GET/POST, e cujos valores são os contratos de validação (veja o objeto DataFilter) de cada parâmetro. Usando a chave ..., é possível aceitar parâmetros não definidos, opcionalmente forçando seu tipo.
• $source (?string): Origem dos parâmetros ('GET' ou 'POST'). Por padrão, a validação opera tanto sobre os dados GET quanto POST (verificando a presença de dados GET e/ou POST).
• $strict (bool): Habilita o modo de validação estrita (veja o objeto DataFilter).
• &$output (mixed): Variável passada por referência que vai receber os dados de saída do DataFilter (dados validados/filtrados e metadados opcionais).

Exemplos:

// espera os parâmetros 'lastname' e 'firstname'
$request->validateInput(['lastname', 'firstname']);

// espera os parâmetros POST 'id' (inteiro maior ou igual a 100)
// e 'mail' (email terminando com "@test.com")
$request->validateInput(
    [
        'id'   => 'int; min: 100',
        'mail' => 'email; mask: @test.com$',
    ],
    'POST'
);

// aceita todos os parâmetros, desde que possam ser convertidos em inteiros
$request->validateInput(['...' => 'int']);

// valida de forma estrita os parâmetros GET 'lastname' (obrigatório)
// e 'firstname' (opcional), e de forma não estrita o parâmetro 'age' (obrigatório)
$request->validateInput(
    [
        'lastname'   => 'string',
        'firstname?' => 'string',
        'age'        => '~int',
    ],
    'GET',
    true
);

// valida um contrato chamado "user" definido na configuração,
// e declarado da seguinte forma:
// 'validationTypes' => [
//     'user' => [
//         'id?'       => 'int',
//         'lastname'  => 'string',
//         'firstname' => 'string',
//         'age'       => '~int',
//     ]
// ]
$request->validateInput('user');

// valida os parâmetros POST e recupera os dados filtrados
$output = null;
$request->validateInput(
    ['name' => 'string', 'email' => 'email'],
    'POST',
    output: $output
);
// $output contém os dados POST validados/filtrados

validatePayload()

Esse método valida os dados enviados no corpo da requisição (o "payload").

Parâmetros:

• $contract (null|string|array): Definição do contrato de validação. Pode ser de dois tipos:
  • Uma string correspondente a um contrato de validação definido no arquivo de configuração, ou a um objeto de validação.
  • Um contrato de validação (veja o objeto DataFilter).
• $strict (bool): Habilita o modo de validação estrita (veja o objeto DataFilter).
• &$output (mixed): Variável passada por referência que vai receber os dados de saída do DataFilter (dados validados/filtrados e metadados opcionais).

Exemplos:

// valida um fluxo JSON contendo uma lista de inteiros
$request->validatePayload([
    'type'     => 'json',
    'contract' => 'list; contract: int'
]);

// valida um fluxo JSON contendo um array associativo
$request->validatePayload([
    'type'     => 'json',
    'contract' => [
        'type' => 'assoc',
        'keys' => [
            'id'       => 'int',
            'lastname' => 'string; minLen: 2',
            'birthday' => 'date; format: Y-m-d',
            'role'     => 'enum; values: user, member, admin',
            'labels?'  => 'list; contract: string',
        ]
    ]
]);

// valida uma imagem GIF ou PNG codificada em base64
$request->validatePayload('base64; mime: image/gif, image/png');

// valida um fluxo binário contendo um PDF ou uma imagem
$request->validatePayload('binary; mime: application/pdf, image');

// valida um contrato chamado "avatar" definido na configuração,
// e declarado da seguinte forma:
// 'validationTypes' => [
//     'avatar' => 'base64; mime: image; maxLen: 1M'
// ]
$request->validatePayload('avatar');

// valida um fluxo binário e recupera os metadados
$output = null;
$request->validatePayload('binary; mime: image', output: $output);
// $output contém ['binary' => ..., 'mime' => ..., 'charset' => ...]

validateFiles()

Esse método valida os arquivos enviados (upload).

Parâmetros:

• $contracts (array): Array associativo cujas chaves são os nomes dos arquivos, e cujos valores são os contratos de validação (veja o objeto DataFilter) de cada arquivo.
• $strict (bool): Habilita o modo de validação estrita (veja o objeto DataFilter).

Exemplos:

// valida um arquivo JSON obrigatório chamado "definition"
// e uma imagem opcional chamada "avatar"
$request->validateFiles([
    'definition' => 'json',
    'avatar?'    => 'binary; mime: image',
]);

// valida um fluxo JSON contendo um inteiro, e qualquer quantidade de arquivos PDF
$request->validateFiles([
    'count' => 'json; contract: int',
    '...'    => 'binary; mime: application/pdf',
]);

---

4Response

4.1Response: visão geral

Esse objeto é usado para recuperar e manipular as informações utilizadas para gerar a resposta enviada pelo Temma ao navegador.

O objeto de resposta está disponível nos controladores e nos plugins ao escrever:

$this->_response

Nos outros objetos gerenciados pelo componente de injeção de dependências, o objeto de resposta é acessível ao escrever:

$this->_loader->response

---

4.2Response: métodos de leitura

// recupera a URL de redirecionamento (ou null)
$url = $this->_response->getRedirection();

// recupera o código de redirecionamento (301 ou 302)
$code = $this->_response->getRedirectionCode();

// recupera o código de erro HTTP (ou null)
$httpError = $this->_response->getHttpError();

// recupera o código de retorno HTTP
$httpCode = $this->_response->getHttpCode();

// recupera o nome da visão definida
$view = $this->_response->getView();

// recupera o prefixo de templates
$prefix = $this->_response->getTemplatePrefix();

// recupera o template definido (ou null)
$tpl = $this->_response->getTemplate();

// recupera a lista de cabeçalhos HTTP
$headers = $this->_response->getHeaders();

// recupera todas as variáveis de template definidas
$vars = $this->_response->getData();
// recupera uma variável de template
$var = $this->_response->getData('var');
// recupera uma variável de template com um valor padrão
// (se o valor padrão for usado, ele é adicionado às variáveis de template)
$var = $this->_response->getData('var', 'default');
// recupera uma variável de template, usando uma função anônima
// para definir o valor padrão
$var = $this->_response->getData('var', function() {
    return 'default';
});
// igual ao anterior, mas fornecendo um parâmetro para a função anônima
$var = $this->_response->getData('var', function($param) {
    return $param * 2;
}, $outroValor);

---

4.3Response: métodos de escrita

// define um redirecionamento temporário (código 302)
$this->_response->setRedirection($url);
// define um redirecionamento permanente (código 301)
$this->_response->setRedirection($url, true);
// redireciona para o referer HTTP, com fallback para $url (código 302)
$this->_response->setRedirection($url, false, true);
// redirecionamento 301 para o referer HTTP, com fallback para $url
$this->_response->setRedirection($url, true, true);

// define o código de erro HTTP
$this->_response->setHttpError(500);

// define o código de retorno HTTP
$this->_response->setHttpCode(404);

// define o nome da visão
$this->_response->setView('\Temma\Views\Json');
$this->_response->setView('~Json');
// desativa o processamento da visão
$this->_response->setView(false);

// adiciona uma variável de template
$this->_response['key'] = 'value';
// remove uma variável de template
unset($this->_response['key']);
// redefine todas as variáveis de template
$this->_response->setData([
    'key1' => 'value1',
    'key2' => 'value2',
]);
// adiciona várias variáveis de template
$this->_response->addData([
    'key3' => 'value3',
    'key4' => 'value4',
]);
// remove todas as variáveis de template
$this->_response->clearData();

// define o prefixo de template
$this->_response->setTemplatePrefix($prefix);

// define o caminho do template
$this->_response->setTemplate('article/voir.tpl');

// adiciona um cabeçalho HTTP
$this->_response->header('Content-Type: application/pdf');

---

4.4Response: métodos de validação

O objeto Response oferece dois métodos para gerenciar um contrato de validação dos dados de saída, que pode ser usado pela visão para validar os dados antes de enviá-los ao navegador.

As validações se baseiam em contratos no formato esperado pelo objeto DataFilter.

setValidationContract()

Esse método define o contrato de validação dos dados de saída.

Parâmetros:

• $contract (null|string|array): Definição do contrato de validação. Pode ser de três tipos:
  • null para remover o contrato de validação.
  • Uma string correspondente a um contrato de validação definido no arquivo de configuração, ou a um objeto de validação.
  • Um contrato de validação (veja o objeto DataFilter).

Exemplos:

// define um contrato nomeado, definido na configuração
$this->_response->setValidationContract('contractName');

// define um contrato como um array
$this->_response->setValidationContract([
    'key1' => 'int',
    'key2' => 'string; minLen: 2',
]);

// remove o contrato de validação
$this->_response->setValidationContract(null);

getValidationContract()

Esse método retorna o contrato de validação definido, ou null se nenhum contrato tiver sido definido.

Exemplo:

// recupera o contrato de validação dos dados de saída
$contract = $this->_response->getValidationContract();