danielspk/tornadohttp

Middleware Container PSR-15

4.0.1 2021-11-17 17:15 UTC

Requires

• php: >=8.0.0
• psr/container: ^1.0
• psr/http-message: ^1.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0

Requires (Dev)

• laminas/laminas-diactoros: ^2.6
• laminas/laminas-servicemanager: ^3.6
• phpunit/phpunit: ^9.5

MIT

• Daniel M. Spiridione

• container
• php
• http
• rest
• dms
• middleware
• tornado
• danielspk
• psr-15
• psr15
• tornado-http

README

TORNADO HTTP es un handler de middlewares PSR-15

Documentación:

La siguiente documentación le enseñará el uso de Tornado Http.

Instalación:

Se recomienda instalar esta librería mediante el uso de Composer de la siguiente forma:

    php composer.phar require danielspk/tornadohttp:~4.0

Esto instalará Tornado HTTP y creará o actualizará el archivo composer.json con la siguiente dependencia:

{
    "require": {
        "danielspk/tornadohttp": "~4.0"
    }
}

Crear el contenedor de aplicación:

Tornado Http puede construirse de varias formas:

Sin parámetros:

    $app = new \DMS\TornadoHttp\TornadoHttp();

Con una cola de Middlewares

    $app = new \DMS\TornadoHttp\TornadoHttp(
        [
            ['middleware' => (new MiddlewareClass)],
            ['middleware' => $middlewareOne],
            ['middleware' => 'ServiceMiddlewareTwo'],
            ['middleware' => 'App\MiddlewareThree', 'path' => '/admin'],
            ['middleware' => ['App\MiddlewareFour', [$paramOne, $paramTwo]]],
        ]
    );

Nota: Puede ver que hay cuatro formas de registrar un Middleware: a) instancia de MiddlewareInterface, b) string con referencia a un servicio del container, c) string con referencia de namespace de clase y d) string con referencia de clase y array con parámetros de constructor. Más adelante se explicará en detalle cada una de estas formas.

Con una Respuesta por defecto

    $app = new DMS\TornadoHttp\TornadoHttp(
        [],
        new DefaultResponse()
    );

Con un Contenedor de Servicios

    $app = new DMS\TornadoHttp\TornadoHttp(
        [],
        new DefaultResponse(),
        new Container()
    );

Nota: El contenedor de servicios a utilizar debe respetar el estándar PSR-11.

Con un Resolver de Middleware personalizado

    $resolver = class () implements ResolverInterface {
        public function solve($middleware) : MiddlewareInterface {
            // ...
        };
    };

    $app = new DMS\TornadoHttp\TornadoHttp(
        [],
        new DefaultResponse(),
        new Container(),
        new $resolver()
    );

Con un Entorno de Ejecución

    $app = new DMS\TornadoHttp\TornadoHttp(
        [],
        new DefaultResponse(),
        new Container(),
        null,
        'development'
    );

Cola de Middlewares:

Tornado Http permite registrar middlewares de 3 formas distintas:

• mediante su constructor
• mediante el método add()
• mediante el método addList()

Ejemplos:

    // mediante el constructor
    $app = new DMS\TornadoHttp\TornadoHttp(
        [
            ['middleware' => (new MiddlewareClass)],
        ]
    );

    // mediante el método add()
    $app->add('ServiceMiddleware', '/', ['GET', 'POST'], ['dev', 'prod'], 0);

    // mediante el método addList()
    $app->addList([
        ['middleware' => (new MiddlewareClass)],
        ['middleware' => 'ServiceMiddleware'],
    ]);

Tornado Http dispone de una clase propia que resuelve automáticamente como ejecutar un middleware registrado.

Existen cuatro formas por defecto de registrar middlewares en Tornado Http utilizando su Resolver:

• mediante una instancia de clase
• mediante un string que hace referencia a un servicio contenido en el Contenedor de Servicios
• mediante un string que hace referencia un namespace de una clase
• mediante un array

Todos los middlewares deben implementar \Psr\Http\Server\MiddlewareInterface.

Ejemplos:

    // mediante una instancia de clase
    $app->add(new MiddlewareClass);

    // mediante un string de referencia a un servicio del contenedor
    $app->add('ServiceMiddleware');

    // mediante un string de referencia a un namespace de clase
    $app->add(App\MiddlewareClass::class);

    // mediante un string de referencia a un namespace de clase y parámetros de constructor
    $app->add([App\MiddlewareClass::class, [$param1, $param2]]);

Cada middleware puede ser registrado con los siguientes filtros de ejecución opcionales:

• Métodos HTTP permitidos
• Path URL
• Entornos de ejecución permitidos

Ejemplos:

    // mediante el constructor
    $app = new DMS\TornadoHttp\TornadoHttp(
        [
            [
                'middleware' => (new MiddlewareTimeExecutionClass),
                'path'       => '/admin',
                'env'        => ['develop'],
            ],
            [
                'middleware' => (new MiddlewareLogClass),
                'methods'    => ['POST', 'PUT'],
                'env'        => ['production', 'develop'],
            ],
        ]
    );

Container Trait:

Tornado Http facilita un trait que puede ser utilizado dentro de los middlewares.

Cuando Tornado Http detecta que un middleware utiliza Container\ContainerTrait inyecta automáticamente el contenedor de servicios registrado en Tornado Http.

Se podrá acceder al contenedor de servicios, dentro del middleware, de la siguiente forma:

    class ExampleMiddleware implements \Psr\Http\Server\MiddlewareInterface
    {
        use \DMS\TornadoHttp\Container\ContainerTrait;

        public function getViewEngine()
        {
            return $this->getContainer()->get('view_engine');
        }

        // ...
    }

Custom Resolver:

Tornado Http permite registrar un resolver de middlewares personalizado. De esta forma puede reemplazar o extender el uso de las cuatro formas mencionadas para registrar middlewares.

Ejemplo:

    class CustomResolver implements ResolverInterface {
        public function solve(string $middlewareClass) : MiddlewareInterface {
            return new $middlewareClass();
        }
    }

    $app = new DMS\TornadoHttp\TornadoHttp();
    $app->setResolver(new CustomResolver());

Resumen de Interfaces/Traits/Clases y Métodos:

DMS\TornadoHttp\TornadoHttp

DMS\TornadoHttp\Container\ContainerTrait

DMS\TornadoHttp\Container\InjectContainerInterface

DMS\TornadoHttp\Middleware\Middleware

DMS\TornadoHttp\Resolver\Resolver

DMS\TornadoHttp\Resolver\ResolverInterface

Inspiración:

• Relay
• Zend Stratigility

Licencia:

El proyecto se distribuye bajo la licencia MIT.

Sugerencias y colaboración:

Daniel Spiridione - http://daniel-spiridione.com.ar