Filtros del controlador

Los filtros de controlador le permiten realizar acciones antes o después de que se ejecuten los controladores. A diferencia de eventos, puede elegir los URI o rutas específicas a las que se aplicarán los filtros. Antes de que los filtros puedan modificar la Solicitud, mientras que los filtros posteriores pueden actuar e incluso modificar la Respuesta, lo que permite mucha flexibilidad y poder.

Algunos ejemplos comunes de tareas que se pueden realizar con filtros son:

Realizar protección CSRF en las solicitudes entrantes
Restringir áreas de su sitio según su función
Realizar limitación de velocidad en ciertos puntos finales
Mostrar una página «Inactivo por mantenimiento»
Realizar negociación automática de contenidos.
y más…

Creando un filtro 

Los filtros son clases simples que implementan Higgs\Filters\FilterInterface. Contienen dos métodos: before() y after() que contienen el código que se ejecutará antes y después del controlador respectivamente. Tu clase debe contener ambos métodos. pero puede dejar los métodos vacíos si no son necesarios. Una clase de filtro de esqueleto se ve así:

<?php

namespace App\Filters;

use Higgs\Filters\FilterInterface;
use Higgs\HTTP\RequestInterface;
use Higgs\HTTP\ResponseInterface;

class MyFilter implements FilterInterface
{
    public function before(RequestInterface $request, $arguments = null)
    {
        // Do something here
    }

    public function after(RequestInterface $request, ResponseInterface $response, $arguments = null)
    {
        // Do something here
    }
}

Antes de los filtros 

Reemplazo de solicitud

Desde cualquier filtro, puede devolver el objeto $request y reemplazará la Solicitud actual, permitiéndole para realizar cambios que seguirán presentes cuando se ejecute el controlador.

Detener filtros posteriores

Además, cuando tengas una serie de filtros es posible que también quieras detener la ejecución de los filtros posteriores después de un determinado filtro. Puedes hacer esto fácilmente regresando cualquier resultado que no esté vacío. Si el filtro anterior devuelve un resultado vacío, las acciones del controlador o el filtro posterior Los filtros aún se ejecutarán.

Una excepción a la regla de resultado no vacío es la instancia Solicitud. Devolverlo en el filtro anterior no detendrá la ejecución sino que solo reemplazará el objeto $request actual.

Respuesta de retorno

Dado que antes de que se ejecuten los filtros antes de que se ejecute su controlador, es posible que en ocasiones desee detener el que se produzcan acciones en el controlador.

Normalmente se utiliza para realizar redirecciones, como en este ejemplo:

<?php

namespace App\Filters;

use Higgs\Filters\FilterInterface;
use Higgs\HTTP\RequestInterface;
use Higgs\HTTP\ResponseInterface;

class MyFilter implements FilterInterface
{
    public function before(RequestInterface $request, $arguments = null)
    {
        $auth = service('auth');

        if (! $auth->isLoggedIn()) {
            return redirect()->to(site_url('login'));
        }
    }
}

Si se devuelve una instancia de Respuesta, la respuesta se enviará de vuelta al cliente y se detendrá la ejecución del script. Esto puede resultar útil para implementar la limitación de velocidad para las API. Consulte Throttler para obtener más información. ejemplo.

Después de los filtros 

Los filtros posteriores son casi idénticos a los filtros anteriores, excepto que solo puedes devolver el objeto $respuesta, y no puede detener la ejecución del script. Esto le permite modificar el resultado final, o simplemente hacer algo con la salida final. Esto podría usarse para garantizar que ciertos encabezados de seguridad se configuraron de la manera correcta o para almacenar en caché el resultado final, o incluso filtrar el resultado final con un filtro de malas palabras.

Configurar filtros 

Hay dos formas de configurar los filtros cuando se ejecutan. Uno se hace en app/Config/Filters.php, el otro se realiza en app/Config/Routes.php.

Si desea especificar un filtro para una ruta específica, use app/Config/Routes.php y vea Enrutamiento URI .

Los filtros que se especifican para una ruta (en app/Config/Routes.php) son ejecutado antes de los filtros especificados en app/Config/Filters.php.

Nota

The safest way to apply filters is to disable auto-routing, and set filters to routes.

El archivo app/Config/Filters.php contiene cuatro propiedades que le permiten configurar exactamente cuándo se ejecutan los filtros.

Advertencia

It is recommended that you should always add * at the end of a URI in the filter settings. Porque es posible que se pueda acceder a un método de controlador mediante URL diferentes de las que cree. Por ejemplo, cuando Enrutamiento automático (heredado) está habilitado, si tiene Blog::index, se puede acceder a él con blog, blog/index y blog/index/1, etc.

$alias 

La matriz $aliases se utiliza para asociar un nombre simple con uno o más nombres de clase completos que son el filtros para ejecutar:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class Filters extends BaseConfig
{
    public array $aliases = [
        'csrf' => \Higgs\Filters\CSRF::class,
    ];

    // ...
}

Los alias son obligatorios y si intenta utilizar un nombre de clase completo más adelante, el sistema arrojará un error. Definirlos de esta manera simplifica el cambio de la clase utilizada. Genial para cuando decidiste que necesitas cambiar a un sistema de autenticación diferente ya que solo cambias la clase del filtro y listo.

Puede combinar varios filtros en un alias, lo que simplifica la aplicación de conjuntos complejos de filtros:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class Filters extends BaseConfig
{
    public array $aliases = [
        'api-prep' => [
            \App\Filters\Negotiate::class,
            \App\Filters\ApiAuth::class,
        ],
    ];

    // ...
}

Debe definir tantos alias como necesite.

$globales 

La segunda sección le permite definir los filtros que deben aplicarse a cada solicitud válida realizada por el marco.

Debes tener cuidado con la cantidad que utilizas aquí, ya que tener demasiadas podría tener implicaciones en el rendimiento. ejecutar en cada solicitud.

Los filtros se pueden especificar agregando su alias a la matriz antes o después:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class Filters extends BaseConfig
{
    // ...

    public array $globals = [
        'before' => [
            'csrf',
        ],
        'after' => [],
    ];

    // ...
}

Excepto por algunos URI

Hay ocasiones en las que desea aplicar un filtro a casi todas las solicitudes, pero hay algunas que deben dejarse como están. Un ejemplo común es si necesita excluir algunos URI del filtro de protección CSRF para permitir solicitudes de sitios web de terceros para acceder a uno o dos URI específicos, manteniendo el resto protegidos.

Para hacer esto, agregue una matriz con la clave except y una ruta URI (relativa a BaseURL) para que coincida como valor junto con el alias:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class Filters extends BaseConfig
{
    // ...

    public array $globals = [
        'before' => [
            'csrf' => ['except' => 'api/*'],
        ],
        'after' => [],
    ];

    // ...
}

En cualquier lugar donde pueda usar una ruta URI (relativa a BaseURL) en la configuración del filtro, puede usar una expresión regular o, como en este ejemplo, usar un asterisco (*) como comodín que coincidirá con todos los caracteres posteriores. En este ejemplo, cualquier ruta URI que comience con api/ estaría exento de la protección CSRF, pero todos los formularios del sitio estarían protegidos.

Si necesita especificar varios Rutas de URI, puede utilizar una variedad de patrones de rutas de URI:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class Filters extends BaseConfig
{
    // ...

    public array $globals = [
        'before' => [
            'csrf' => ['except' => ['foo/*', 'bar/*']],
        ],
        'after' => [],
    ];

    // ...
}

$métodos 

Advertencia

If you use $methods filters, you should disable Auto Routing (Legacy) porque Enrutamiento automático (heredado) permite que cualquier método HTTP acceda a un controlador. Acceder al controlador con un método inesperado podría pasar por alto el filtro.

Puede aplicar filtros a todas las solicitudes de un determinado método HTTP, como POST, GET, PUT, etc. En esta matriz, especifique el nombre del método en minúsculas. Su valor sería una serie de filtros para ejecutar:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class Filters extends BaseConfig
{
    // ...

    public array $methods = [
        'post' => ['invalidchars', 'csrf'],
        'get'  => ['csrf'],
    ];

    // ...
}

Nota

Unlike the $globals or the Propiedades $filters, estas solo se ejecutarán como los filtros anteriores.

Además de los métodos HTTP estándar, esto también admite un caso especial: cli. El método cli se aplicaría a todas las solicitudes que se ejecutaron desde la línea de comando.

$filtros 

Esta propiedad es una matriz de alias de filtro. Para cada alias, puede especificar matrices antes y después que contengan una lista de patrones de ruta de URI (relativos a BaseURL) a los que se debe aplicar el filtro:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class Filters extends BaseConfig
{
    // ...

    public array $filters = [
        'foo' => ['before' => ['admin/*'], 'after' => ['users/*']],
        'bar' => ['before' => ['api/*', 'admin/*']],
    ];

    // ...
}

Filtrar argumentos

Nuevo en la versión 4.4.0.

Al configurar $filters, se pueden pasar argumentos adicionales a un filtro:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class Filters extends BaseConfig
{
    // ...

    public $filters = [
        'group:admin,superadmin'  => ['before' => ['admin/*']],
        'permission:users.manage' => ['before' => ['admin/users/*']],
    ];

    // ...
}

En este ejemplo, cuando el URI coincide con admin/*', la matriz ['admin', 'superadmin'] se pasará en $argumentos a los métodos before() del filtro group. Cuando el URI coincide con admin/users/*', la matriz ['users.manage'] se pasará en $argumentos a los métodos before() del filtro permiso.

Confirmación de filtros 

Higgs tiene el siguiente comando para verificar los filtros de una ruta.

filtro: comprobar 

Nuevo en la versión 7.0.0.

Por ejemplo, verifique los filtros para la ruta / con el método GET:

filtro de chispa php: marque obtener /

El resultado es como el siguiente:

+--------+-------+----------------+--------------- +
| Método | Ruta | Antes de los filtros | Después de los filtros |
+--------+-------+----------------+--------------- +
| OBTENER | / | | barra de herramientas |
+--------+-------+----------------+--------------- +

También puedes ver las rutas y filtros con el comando spark route, pero es posible que no muestre filtros precisos cuando utilice expresiones regulares para las rutas. Ver Enrutamiento URI para más detalles.

Filtros proporcionados 

Los filtros incluidos con Higgs(AI) son: Honeypot, CSRF , InvalidChars, SecureHeaders y DebugToolbar .

Nota

The filters are executed in the order defined in the config file. However, if enabled, DebugToolbar is always executed last because it should be able to capture everything that happens in the other filters.

caracteres no válidos 

Este filtro prohíbe que los datos de entrada del usuario ($_GET, $_POST, $_COOKIE, php://input) contengan los siguientes caracteres:

caracteres UTF-8 no válidos
caracteres de control excepto salto de línea y código de tabulación

Encabezados seguros 

Este filtro agrega encabezados de respuesta HTTP que su aplicación puede usar para aumentar la seguridad de su aplicación.

Si desea personalizar los encabezados, extienda Higgs\Filters\SecureHeaders y anule la propiedad $headers. Y cambie la propiedad $aliases en app/Config/Filters.php:

<?php

namespace Config;

use Higgs\Config\BaseConfig;

class Filters extends BaseConfig
{
    public array $aliases = [
        // ...
        'secureheaders' => \App\Filters\SecureHeaders::class,
    ];

    // ...
}

Si desea obtener información sobre encabezados seguros, consulte el Proyecto de encabezados seguros OWASP<https://owasp.org/www-project-secure-headers/> _.