Objetos internos

---

1Visión general

Cuando Temma ejecuta una petición, instancia varios objetos que son necesarios para ese procesamiento, y los pone a disposición de los controladores y los plugins.

Estos objetos son de tipo:

• \Temma\Base\Session: gestión de las sesiones de usuario (ver la documentación dedicada).
• \Temma\Web\Config: recuperación de la información de configuración.
• \Temma\Web\Request: recuperación y modificación de los datos que componen la petición.
• \Temma\Web\Response: control de determinados parámetros de la respuesta.

---

2Config

2.1Config: visión general

Este objeto se usa para acceder y modificar la configuración del sitio durante la petición actual.

El objeto de configuración está disponible en los controladores y en los plugins escribiendo:

$this->_config

En los demás objetos gestionados por el componente de inyección de dependencias, el objeto de configuración es accesible escribiendo:

$this->_loader->config

---

2.2Config: atributos de lectura y escritura

• appPath : (string) ruta a la raíz del proyecto
• etcPath : (string) ruta al directorio 'etc' del proyecto
• logPath : (string) ruta al directorio 'log' del proyecto
• tmpPath : (string) ruta al directorio 'tmp' del proyecto
• includesPath : (string) ruta al directorio 'lib' del proyecto
• controllersPath : (string) ruta al directorio 'controllers' del proyecto
• varPath : (string) ruta al directorio 'var' del proyecto
• webPath : (string) ruta al directorio 'www' del proyecto
• routes : (array) enrutamiento básico
• plugins : (array) lista de plugins
• enableSessions : (bool) indica si las sesiones están habilitadas
• rootController : (string) nombre del controlador raíz
• defaultController : (string) nombre del controlador por defecto
• proxyController : (string) nombre del controlador proxy
• defaultNamespace : (string) namespace por defecto de los controladores
• defaultView : (string) nombre de la vista por defecto
• loader : (string) nombre del objeto usado como componente de inyección de dependencias
• loaderAliases : (?array) array asociativo que contiene los alias de nomenclatura gestionados por el loader
• loaderPrefixes : (?array) array asociativo que contiene los prefijos de nomenclatura gestionados por el loader
• logManager : (null|string|array) nombre del o los gestores de log
• logLevels : (null|string|array) umbrales de log
• bufferingLogLevels : (null|string|array) umbrales de log en buffer

---

2.3Config: gestión de configuraciones extendidas

El método xtra() se usa para leer una configuración extendida:

// recupera toda la configuración extendida "x-user"
$conf = $this->_config->xtra('user');

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

// recupera la clave "login", con valor por defecto
$login = $this->_config->xtra('user', 'login', 'admin');

El método setXtra() se usa para definir una clave en una configuración extendida:

// define la clave "login" en la configuración extendida "x-user"
$this->_config->setXtra('user', 'login', 'sysop');

---

3Request

3.1Request: visión general

La gestión de la petición se usa raramente en los controladores de la aplicación. Sin embargo, puede ser útil en plugins que quieran controlar el flujo de ejecución cambiando las características de la petición.

El objeto de petición está disponible en los controladores y en los plugins escribiendo:

$this->_request

En los demás objetos gestionados por el componente de inyección de dependencias, el objeto de petición es accesible escribiendo:

$this->_loader->request

---

3.2Request: métodos de lectura

// averigua si es una petición AJAX
$ajax = $this->_request->isAjax();

// recupera los formatos de datos aceptados por el navegador
// ("text/html", "application/json", "image/png", etc.)
$formats = $this->_request->getAcceptedFormats();

// indica si un formato dado es aceptado por el navegador
// ("text/html", "text", "image/png", "image", "*/*", "*", etc.)
$bool = $this->_request->isAcceptedFormat($format);

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

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

// recupera el nombre del controlador
$ctrl = $this->_request->getController();

// recupera el nombre de la acción
$action = $this->_request->getAction();

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

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

// recupera el primer parámetro
$p1 = $this->_request->getParam(0);
// recupera el 2º parámetro, con un valor por defecto
$p2 = $this->_request->getParam(1, 'toto');

// recupera la ruta desde la raíz del sitio
$path = $this->_request->getSitePath();

---

3.3Request: métodos de escritura

// definición del método
$this->_request->setMethod('POST');

// definición del controlador
$this->_request->setController('user');
// recomendado: actualizar la variable de plantilla asociada
$this['CONTROLLER'] = 'user';

// definición de la acción
$this->_request->setAction('list');
// recomendado: actualizar la variable de plantilla asociada
$this['ACTION'] = 'list';

// definición de la lista de parámetros
$this->_request->setParams(['toto', 'titi']);

// definición del segundo parámetro
$this->_request->setParam(1, 'tata');

---

3.4Request: métodos de validación

El objeto Request ofrece cuatro métodos para validar los datos recibidos : validateParams(), validateInput(), validatePayload() y validateFiles().

Las validaciones se basan en contratos con el formato esperado por el objeto DataFilter.

Estos métodos lanzan una excepción \Temma\Exceptions\Application si los datos no son válidos. Lanzan una excepción \Temma\Exceptions\IO si un contrato es incorrecto.

validateParams()

Este método valida los parámetros recibidos en la URL.

En modo de validación no estricto (comportamiento por defecto), los parámetros pueden modificarse : una string que supere la longitud máxima definida se truncará, los tipos se convierten si es necesario, los parámetros no definidos se eliminan, etc.

Parámetros:

• $contract (null|string|array) : Definición del contrato de validación. Puede ser de dos tipos :
  • Una string correspondiente a un contrato de validación definido en el archivo de configuración, o a un objeto de validación.
  • Una lista de contratos (ver el objeto DataFilter), con un contrato por parámetro. Es posible especificar ... para indicar que los parámetros siguientes se aceptan tal cual.
• $strict (bool) : Activa el modo de validación estricto (ver el objeto DataFilter).
• &$output (mixed) : Variable pasada por referencia que recibirá los datos de salida de DataFilter (datos validados/filtrados y metadatos opcionales).

Si se proporcionan más parámetros de los definidos, y no hay una entrada ... en la lista de contratos :

• En modo no estricto, los parámetros adicionales se eliminan.
• En modo estricto, se lanza una excepción.

Ejemplos :

// valida que el primer parámetro sea un entero mayor o igual que 20
// y que el segundo sea un color hexadecimal
$request->validateParams(['int; min: 20', 'color']);

// valida que el primer parámetro sea un entero positivo,
// que el segundo sea una enumeración, y que el tercero sea una string
// que empiece por "foo"
$request->validateParams([
    'int; min: 0',
    'enum; values: member, admin',
    'string; mask: ^foo'
]);

// valida que el primer parámetro sea un entero
// y que se permitan parámetros adicionales
$request->validateParams(['int', '...']);

// valida un contrato llamado "userUpdateParams" definido en la configuración,
// y declarado de la siguiente forma:
// 'validationTypes' => [
//     'userUpdateParams' => 'list; values: int, int, string'
// ]
$request->validateInput('userUpdateParams');

// valida y recupera los datos filtrados
$output = null;
$request->validateParams(['int; min: 1', 'slug'], output: $output);
// $output contiene los parámetros validados

validateInput()

Este método valida los datos recibidos como parámetros GET o POST.

En modo de validación no estricto (comportamiento por defecto), los parámetros GET/POST pueden modificarse: una string que supere la longitud máxima definida se truncará, los tipos se convierten si es necesario, los parámetros no definidos se eliminan, etc.

Parámetros:

• $contract (null|string|array) : Definición del contrato de validación. Puede ser de dos tipos :
  • Una string correspondiente a un contrato de validación definido en el archivo de configuración, o a un objeto de validación.
  • Array asociativo cuyas claves son los parámetros GET/POST, y cuyos valores son los contratos de validación (ver el objeto DataFilter) de cada parámetro. Usando la clave ... es posible aceptar parámetros no definidos, forzando opcionalmente su tipo.
• $source (?string) : Origen de los parámetros ('GET' o 'POST'). Por defecto, la validación opera tanto sobre los datos GET como POST (comprobando la presencia de datos GET y/o POST).
• $strict (bool) : Activa el modo de validación estricto (ver el objeto DataFilter).
• &$output (mixed) : Variable pasada por referencia que recibirá los datos de salida de DataFilter (datos validados/filtrados y metadatos opcionales).

Ejemplos:

// espera los parámetros 'lastname' y 'firstname'
$request->validateInput(['lastname', 'firstname']);

// espera los parámetros POST 'id' (entero mayor o igual que 100)
// y 'mail' (email que termine en "@test.com")
$request->validateInput(
    [
        'id'   => 'int; min: 100',
        'mail' => 'email; mask: @test.com$',
    ],
    'POST'
);

// acepta todos los parámetros, siempre que puedan convertirse en enteros
$request->validateInput(['...' => 'int']);

// valida de forma estricta los parámetros GET 'lastname' (obligatorio)
// y 'firstname' (opcional), y de forma no estricta el parámetro 'age' (obligatorio)
$request->validateInput(
    [
        'lastname'   => 'string',
        'firstname?' => 'string',
        'age'        => '~int',
    ],
    'GET',
    true
);

// valida un contrato llamado "user" definido en la configuración,
// y declarado de la siguiente forma:
// 'validationTypes' => [
//     'user' => [
//         'id?'       => 'int',
//         'lastname'  => 'string',
//         'firstname' => 'string',
//         'age'       => '~int',
//     ]
// ]
$request->validateInput('user');

// valida los parámetros POST y recupera los datos filtrados
$output = null;
$request->validateInput(
    ['name' => 'string', 'email' => 'email'],
    'POST',
    output: $output
);
// $output contiene los datos POST validados/filtrados

validatePayload()

Este método valida los datos enviados en el cuerpo de la petición (el "payload").

Parámetros :

• $contract (null|string|array) : Definición del contrato de validación. Puede ser de dos tipos :
  • Una string correspondiente a un contrato de validación definido en el archivo de configuración, o a un objeto de validación.
  • Un contrato de validación (ver el objeto DataFilter).
• $strict (bool) : Activa el modo de validación estricto (ver el objeto DataFilter).
• &$output (mixed) : Variable pasada por referencia que recibirá los datos de salida de DataFilter (datos validados/filtrados y metadatos opcionales).

Ejemplos:

// valida un flujo JSON que contiene una lista de enteros
$request->validatePayload([
    'type'     => 'json',
    'contract' => 'list; contract: int'
]);

// valida un flujo JSON que contiene un array asociativo
$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 una imagen GIF o PNG codificada en base64
$request->validatePayload('base64; mime: image/gif, image/png');

// valida un flujo binario que contiene un PDF o una imagen
$request->validatePayload('binary; mime: application/pdf, image');

// valida un contrato llamado "avatar" definido en la configuración,
// y declarado de la siguiente forma:
// 'validationTypes' => [
//     'avatar' => 'base64; mime: image; maxLen: 1M'
// ]
$request->validatePayload('avatar');

// valida un flujo binario y recupera los metadatos
$output = null;
$request->validatePayload('binary; mime: image', output: $output);
// $output contiene ['binary' => ..., 'mime' => ..., 'charset' => ...]

validateFiles()

Este método valida los archivos subidos.

Parámetros :

• $contracts (array) : Array asociativo cuyas claves son los nombres de los archivos, y cuyos valores son los contratos de validación (ver el objeto DataFilter) de cada archivo.
• $strict (bool) : Activa el modo de validación estricto (ver el objeto DataFilter).

Ejemplos :

// valida un archivo JSON obligatorio llamado "definition"
// y una imagen opcional llamada "avatar"
$request->validateFiles([
    'definition' => 'json',
    'avatar?'    => 'binary; mime: image',
]);

// valida un flujo JSON que contiene un entero, y cualquier cantidad de archivos PDF
$request->validateFiles([
    'count' => 'json; contract: int',
    '...'    => 'binary; mime: application/pdf',
]);

---

4Response

4.1Response: visión general

Este objeto se usa para recuperar y manipular la información utilizada para generar la respuesta que Temma envía al navegador.

El objeto de respuesta está disponible en los controladores y en los plugins escribiendo:

$this->_response

En los demás objetos gestionados por el componente de inyección de dependencias, el objeto de respuesta es accesible escribiendo:

$this->_loader->response

---

4.2Response: métodos de lectura

// recupera la URL de redirección (o null)
$url = $this->_response->getRedirection();

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

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

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

// recupera el nombre de la vista definida
$view = $this->_response->getView();

// recupera el prefijo de plantillas
$prefix = $this->_response->getTemplatePrefix();

// recupera la plantilla definida (o null)
$tpl = $this->_response->getTemplate();

// recupera la lista de cabeceras HTTP
$headers = $this->_response->getHeaders();

// recupera todas las variables de plantilla definidas
$vars = $this->_response->getData();
// recupera una variable de plantilla
$var = $this->_response->getData('var');
// recupera una variable de plantilla con un valor por defecto
// (si se usa el valor por defecto, se añade a las variables de plantilla)
$var = $this->_response->getData('var', 'default');
// recupera una variable de plantilla, usando una función anónima
// para definir el valor por defecto
$var = $this->_response->getData('var', function() {
    return 'default';
});
// igual que el anterior, pero proporcionando un parámetro a la función anónima
$var = $this->_response->getData('var', function($param) {
    return $param * 2;
}, $otherValue);

---

4.3Response: métodos de escritura

// define una redirección temporal (código 302)
$this->_response->setRedirection($url);
// define una redirección permanente (código 301)
$this->_response->setRedirection($url, true);
// redirige al referer HTTP, con reserva de $url (código 302)
$this->_response->setRedirection($url, false, true);
// redirección 301 al referer HTTP, con reserva de $url
$this->_response->setRedirection($url, true, true);

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

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

// define el nombre de la vista
$this->_response->setView('\Temma\Views\Json');
$this->_response->setView('~Json');
// desactiva el procesamiento de la vista
$this->_response->setView(false);

// añade una variable de plantilla
$this->_response['key'] = 'value';
// elimina una variable de plantilla
unset($this->_response['key']);
// redefine todas las variables de plantilla
$this->_response->setData([
    'key1' => 'value1',
    'key2' => 'value2',
]);
// añade varias variables de plantilla
$this->_response->addData([
    'key3' => 'value3',
    'key4' => 'value4',
]);
// elimina todas las variables de plantilla
$this->_response->clearData();

// define el prefijo de plantillas
$this->_response->setTemplatePrefix($prefix);

// define la ruta de la plantilla
$this->_response->setTemplate('article/voir.tpl');

// añade una cabecera HTTP
$this->_response->header('Content-Type: application/pdf');

---

4.4Response: métodos de validación

El objeto Response ofrece dos métodos para gestionar un contrato de validación de los datos de salida, que la vista puede usar para validar los datos antes de enviarlos al navegador.

Las validaciones se basan en contratos con el formato esperado por el objeto DataFilter.

setValidationContract()

Este método define el contrato de validación de los datos de salida.

Parámetros:

• $contract (null|string|array) : Definición del contrato de validación. Puede ser de tres tipos :
  • null para eliminar el contrato de validación.
  • Una string correspondiente a un contrato de validación definido en el archivo de configuración, o a un objeto de validación.
  • Un contrato de validación (ver el objeto DataFilter).

Ejemplos:

// define un contrato con nombre, definido en la configuración
$this->_response->setValidationContract('contractName');

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

// elimina el contrato de validación
$this->_response->setValidationContract(null);

getValidationContract()

Este método devuelve el contrato de validación definido, o null si no se ha definido ningún contrato.

Ejemplo:

// recupera el contrato de validación de los datos de salida
$contract = $this->_response->getValidationContract();