Filtros ¶

Los Filtros (filters) son objetos que se ejecutan antes y/o después de las acciones de controlador. Por ejemplo, un filtro de control de acceso puede ejecutarse antes de las acciones para asegurar que un usuario final tiene permitido acceder a estas; un filtro de compresión de contenido puede ejecutarse después de las acciones para comprimir el contenido de la respuesta antes de ser enviado al usuario final.

Un filtro puede consistir en un pre-filtro (lógica de filtrado aplicada antes de las acciones) y/o un post-filtro (lógica de filtro aplicada después de las acciones).

Uso de Filtros ¶

Los filtros son esencialmente un tipo especial de comportamientos (behaviors). Por lo tanto, usar filtros es lo mismo que uso de comportamientos. Se pueden declarar los filtros en una clase controlador sobrescribiendo el método behaviors() como en el siguiente ejemplo:

public function behaviors()
{
    return [
        [
            'class' => 'yii\filters\HttpCache',
            'only' => ['index', 'view'],
            'lastModified' => function ($action, $params) {
                $q = new \yii\db\Query();
                return $q->from('user')->max('updated_at');
            },
        ],
    ];
}

Por defecto, los filtros declarados en una clase controlador, serán aplicados en todas las acciones de este controlador. Sin embargo, se puede especificar explícitamente en que acciones serán aplicadas configurando la propiedad only. En el anterior ejemplo, el filtro 'HttpCache' solo se aplica a las acciones 'index' y 'view'. También se puede configurar la propiedad except para prevenir que ciertas acciones sean filtradas.

Además de en los controladores, se pueden declarar filtros en módulos o aplicaciones. Una vez hecho, los filtros serán aplicados a todas las acciones de controlador que pertenezcan a ese modulo o aplicación, a menos que las propiedades only y except sean configuradas como se ha descrito anteriormente.

Nota: Cuando se declaran filtros en módulos o aplicaciones, deben usarse rutas en lugar de IDs de acciones en las propiedades only y except. Esto es debido a que los IDs de acciones no pueden especificar acciones dentro del ámbito de un modulo o una aplicación por si mismos.

Cuando se configuran múltiples filtros para una misma acción, se aplican de acuerdo a las siguientes reglas:

• Pre-filtrado
  • Aplica filtros declarados en la aplicación en orden de aparición en behaviors().
  • Aplica filtros declarados en el modulo en orden de aparición en behaviors().
  • Aplica filtros declarados en el controlador en orden de aparición en behaviors().
  • Si hay algún filtro que cancele la ejecución de la acción, los filtros(tanto pre-filtros como post-filtros) posteriores a este no serán aplicados.
• Ejecución de la acción si pasa el pre-filtro.
• Post-filtrado
  • Aplica los filtros declarados en el controlador en el controlador en orden inverso al de aparición en behaviors().
  • Aplica los filtros declarados en el modulo en orden inverso al de aparición en behaviors().
  • Aplica los filtros declarados en la aplicación en orden inverso al de aparición en behaviors().

Creación de Filtros ¶

Para crear un nuevo filtro de acción, hay que extender a yii\base\ActionFilter y sobrescribir los métodos beforeAction() y/o afterAction(). El primero será ejecutado antes de la acción mientras que el segundo lo hará una vez ejecutada la acción. El valor devuelto por beforeAction() determina si una acción debe ejecutarse o no. Si el valor es falso, los filtros posteriores a este serán omitidos y la acción no será ejecutada.

El siguiente ejemplo muestra un filtro que registra el tiempo de ejecución de una acción:

namespace app\components;

use Yii;
use yii\base\ActionFilter;

class ActionTimeFilter extends ActionFilter
{
    private $_startTime;

    public function beforeAction($action)
    {
        $this->_startTime = microtime(true);
        return parent::beforeAction($action);
    }

    public function afterAction($action, $result)
    {
        $time = microtime(true) - $this->_startTime;
        Yii::debug("Action '{$action->uniqueId}' spent $time second.");
        return parent::afterAction($action, $result);
    }
}

Filtros del Núcleo ¶

Yii proporciona una serie de filtros de uso general, que se encuentran principalmente en yii\filters namespace. En adelante introduciremos estos filtros brevemente.

AccessControl ¶

AccessControl proporciona control de acceso simple basado en un conjunto de rules. En concreto, antes de ejecutar una acción, AccessControl examinará la lista de reglas y encontrará la primera que concuerde con las actuales variables de contexto(tales como dirección IP de usuario, estado de inicio de sesión del usuario, etc.). La regla que concuerde dictara si se permite o deniega la ejecución de la acción solicitada. Si ninguna regla concuerda, el acceso será denegado.

El siguiente ejemplo muestra como habilitar el acceso a los usuarios autenticados a las acciones 'create' y 'update' mientras deniega a todos los otros usuarios el acceso a estas dos acciones.

use yii\filters\AccessControl;

public function behaviors()
{
    return [
        'access' => [
            'class' => AccessControl::class,
            'only' => ['create', 'update'],
            'rules' => [
                // permitido para usuarios autenticados
                [
                    'allow' => true,
                    'roles' => ['@'],
                ],
                // todo lo demás se deniega por defecto
            ],
        ],
    ];
}

Para conocer más detalles acerca del control de acceso en general, refiérase a la sección de Autorización

Filtros del Método de Autenticación ¶

Los filtros del método de autenticación se usan para autenticar a un usuario utilizando varios métodos, tales como la Autenticación de acceso básico HTTP, Oauth 2. Estas clases de filtros se encuentran en el espacio de nombres yii\filters\auth.

El siguiente ejemplo muestra como usar yii\filters\auth\HttpBasicAuth para autenticar un usuario usando un token de acceso basado en el método de Autenticación de acceso básico HTTP. Tenga en cuenta que para que esto funcione, la clase user identity class debe implementar el método findIdentityByAccessToken().

use yii\filters\auth\HttpBasicAuth;

public function behaviors()
{
    return [
        'basicAuth' => [
            'class' => HttpBasicAuth::class,
        ],
    ];
}

Los filtros del método de autenticación se usan a menudo para implementar APIs RESTful. Para más detalles, por favor refiérase a la sección Autenticación RESTful.

ContentNegotiator El filtro ContentNegotiator da soporte a la negociación del formato de respuesta y a la negociación del idioma de la aplicación. Este determinara el formato de respuesta y/o el idioma examinando los parámetros 'GET' y 'Accept' del encabezado HTTP.

En el siguiente ejemplo, el filtro ContentNegotiator se configura para soportar los formatos de respuesta 'JSON' y 'XML', y los idiomas Ingles(Estados Unidos) y Alemán.

use yii\filters\ContentNegotiator;
use yii\web\Response;

public function behaviors()
{
    return [
        [
            'class' => ContentNegotiator::class,
            'formats' => [
                'application/json' => Response::FORMAT_JSON,
                'application/xml' => Response::FORMAT_XML,
            ],
            'languages' => [
                'en-US',
                'de',
            ],
        ],
    ];
}

Los formatos de respuesta y los idiomas a menudo precisan ser determinados mucho antes durante el ciclo de vida de la aplicación. Por esta razón, ContentNegotiator esta diseñado de tal manera que se pueda usar como componente de bootstrapping así como de filtro. Por ejemplo, ContentNegotiator se puede configurar en la configuración de la aplicación como en el siguiente ejemplo:

use yii\filters\ContentNegotiator;
use yii\web\Response;

[
    'bootstrap' => [
        [
            'class' => ContentNegotiator::class,
            'formats' => [
                'application/json' => Response::FORMAT_JSON,
                'application/xml' => Response::FORMAT_XML,
            ],
            'languages' => [
                'en-US',
                'de',
            ],
        ],
    ],
];

Información: En el caso que el tipo preferido de contenido y el idioma no puedan ser determinados por una petición, será utilizando el primer elemento de formato e idioma de la lista formats y lenguages.

HttpCache ¶

HttpCache implementa un almacenamiento caché del lado del cliente utilizando las cabeceras HTTP 'Last-Modified' y 'Etag'. Por ejemplo:

use yii\filters\HttpCache;

public function behaviors()
{
    return [
        [
            'class' => HttpCache::class,
            'only' => ['index'],
            'lastModified' => function ($action, $params) {
                $q = new \yii\db\Query();
                return $q->from('user')->max('updated_at');
            },
        ],
    ];
}

Para conocer más detalles acerca de HttpCache refiérase a la sección almacenamiento caché HTTP.

PageCache ¶

PageCache implementa una caché por parte del servidor de paginas enteras. En el siguiente ejemplo, se aplica PageCache a la acción 'index' para generar una cache de la pagina entera durante 60 segundos como máximo o hasta que el contador de entradas de la tabla 'post' varíe. También se encarga de almacenar diferentes versiones de la pagina dependiendo del idioma de la aplicación seleccionado.

use yii\filters\PageCache;
use yii\caching\DbDependency;

public function behaviors()
{
    return [
        'pageCache' => [
            'class' => PageCache::class,
            'only' => ['index'],
            'duration' => 60,
            'dependency' => [
                'class' => DbDependency::class,
                'sql' => 'SELECT COUNT(*) FROM post',
            ],
            'variations' => [
                \Yii::$app->language,
            ]
        ],
    ];
}

Por favor refiérase a Caché de Páginas para obtener más detalles acerca de como usar PageCache.

RateLimiter ¶

RateLimiter implementa un algoritmo de para limitar la tasa de descarga basándose en leaky bucket algorithm. Este se utiliza sobre todo en la implementación de APIs RESTful. Por favor, refiérase a la sección limite de tasa para obtener más detalles acerca de el uso de este filtro.

VerbFilter ¶

VerbFilter comprueba que los métodos de las peticiones HTTP estén permitidas para las acciones solicitadas. Si no están permitidas, lanzara una excepción de tipo HTTP 405. En el siguiente ejemplo, se declara VerbFilter para especificar el conjunto típico métodos de petición permitidos para acciones CRUD.

use yii\filters\VerbFilter;

public function behaviors()
{
    return [
        'verbs' => [
            'class' => VerbFilter::class,
            'actions' => [
                'index'  => ['get'],
                'view'   => ['get'],
                'create' => ['get', 'post'],
                'update' => ['get', 'put', 'post'],
                'delete' => ['post', 'delete'],
            ],
        ],
    ];
}

Cors ¶

CORS es un mecanismo que permite a diferentes recursos (por ejemplo: fuentes, JavaScript, etc) de una pagina Web ser solicitados por otro dominio diferente al dominio que esta haciendo la petición. En particular las llamadas AJAX de JavaScript pueden utilizar el mecanismo XMLHttpRequest. De otro modo esta petición de dominio cruzado seria prohibida por los navegadores Web, por la misma pollita de seguridad de origen. CORS establece la manera en que el navegador y el servidor pueden interaccionar para determinar si se permite o no la petición de dominio cruzado. El filtro Cors filter puede ser definido antes de los filtros Autenticación / Autorización para asegurar que las cabeceras de CORS siempre serán enviadas.

use yii\filters\Cors;
use yii\helpers\ArrayHelper;

public function behaviors()
{
    return ArrayHelper::merge([
        [
            'class' => Cors::class,
        ],
    ], parent::behaviors());
}

El filtrado CORS puede ser ajustado utilizando la propiedad 'cors'.

• cors['Origin']: array utilizado para definir los orígenes permitidos. Puede ser ['*'] (everyone) o ['https://www.myserver.net', 'https://www.myotherserver.com']. Por defecto ['*'].
• cors['Access-Control-Request-Method']: array de los verbos permitidos como ['GET', 'OPTIONS', 'HEAD']. Por defecto ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'].
• cors['Access-Control-Request-Headers']: array de las cabeceras permitidas. Puede ser ['*'] todas las cabeceras o algunas especificas ['X-Request-With']. Por defecto ['*'].
• cors['Access-Control-Allow-Credentials']: define si la petición actual puede hacer uso de credenciales. Puede ser true, false o null (not set). Por defecto null.
• cors['Access-Control-Max-Age']: define el tiempo de vida del la petición pref-flight. Por defecto 86400. Por ejemplo, habilitar CORS para el origen: https://www.myserver.net con métodos GET, HEAD y OPTIONS:

use yii\filters\Cors;
use yii\helpers\ArrayHelper;

public function behaviors()
{
    return ArrayHelper::merge([
        [
            'class' => Cors::class,
            'cors' => [
                'Origin' => ['https://www.myserver.net'],
                'Access-Control-Request-Method' => ['GET', 'HEAD', 'OPTIONS'],
            ],
        ],
    ], parent::behaviors());
}

Se pueden ajustar las cabeceras de CORS sobrescribiendo los parámetros por defecto de una acción. Por ejemplo añadir Access-Control-Allow-Credentials a la acción 'login', se podría hacer así:

use yii\filters\Cors;
use yii\helpers\ArrayHelper;

public function behaviors()
{
    return ArrayHelper::merge([
        [
            'class' => Cors::class,
            'cors' => [
                'Origin' => ['https://www.myserver.net'],
                'Access-Control-Request-Method' => ['GET', 'HEAD', 'OPTIONS'],
            ],
            'actions' => [
                'login' => [
                    'Access-Control-Allow-Credentials' => true,
                ]
            ]
        ],
    ], parent::behaviors());
}