DEV Community: Adrian Garay

CQRS con Symfony Messenger (Español)

Adrian Garay — Mon, 22 Aug 2022 16:30:00 +0000

See the english version

CQRS with Symfony Messenger

Adrian Garay ・ Aug 22 '22

Introducción

Habitualmente usamos la misma estructura de datos para escribir y consultar información en un sistema, para sistemas más grandes esto puede causar estructuras de datos más grandes porque necesita integrar lectura y escritura en el mismo modelo. Por ejemplo, al escribir información podemos necesitar muchas validaciones para asegurarnos de que la información que queremos guardar sea correcta, pedir esta información puede ser diferente y complejo para recuperar datos filtrados o estructuras de datos diferentes para cada caso.

CQRS is a pattern that separates read and update operations for a data store. Implementing CQRS in your application can maximize its performance, scalability, and security. The flexibility created by migrating to CQRS allows a system to better evolve over time and prevents update commands from causing merge conflicts at the domain level.

El patrón de diseño

CQRS separa la estructura de lectura mediante consultas para leer datos y el modelo de escritura mediante comandos para realizar operaciones con los datos

Los comandos deben basarse en tareas, lo que significa que debemos centrarnos en la operación del comando, por ejemplo, en una aplicación de entrega al pedir algo, llamaremos a la operación OrderProductCommand en lugar de AddProductToClient o CreateNewOrderProduct, esto también hace que nuestra capa de aplicación sea más consistente.
Las consultas nunca modifican la base de datos. Una consulta devuelve un DTO que no encapsula ningún conocimiento del dominio. Necesitamos centrarnos en la información necesaria, no en el comportamiento del dominio.

Beneficios

Independent scaling. Permite que los modelos de lectura y escritura se escalen de forma independiente
Optimized data schemas. El modelo de lectura puede usar un esquema optimizado para consultas y el modelo de escritura usa un esquema optimizado para actualizaciones.
Security. Es más fácil asegurarse de que solo las entidades de dominio correctas realicen escrituras.
Separation of concerns. La lógica empresarial compleja entra en el modelo de escritura. El modelo de lectura puede ser simple.

Implementar CQRS con Symfony Messenger

El Componente Messenger ayuda a las aplicaciones a enviar y recibir mensajes hacia/desde otras aplicaciones o mediante colas de mensajes. También nos permite definir buses de mensajes personalizados que definen tipos de mensajes y controladores.

Hablemos de la arquitectura del software.

CommandBus

Hablando de comandos, necesitamos modular una interfaz común que un bus de mensajes pueda administrar y transportar a los controladores, la interfaz de comando termina siendo nuestra interfaz base para cada comando. Cada implementador de Command Handler realizará operaciones con el comando dado, pero el comando en sí mismo no sabe qué operación se realiza. Además, vamos a crear una interfaz para el bus de comandos con el fin de crear diferentes tipos de transportadores para nuestros mensajes (comandos), en este caso, creamos un bus de comandos en memoria, pero podemos ampliar este concepto fácilmente si es necesario (ej: Un trabajo en cola).

Terminaremos con algo así en el código src de nuestra aplicación Symfony.

<?php

declare(strict_types=1);

namespace App\Shared\Domain\Bus\Command;

interface Command
{
}

<?php

declare(strict_types=1);

namespace App\Shared\Domain\Bus\Command;

interface CommandBus
{
    public function dispatch(Command $command) : void;
}

<?php

declare(strict_types=1);

namespace App\Shared\Domain\Bus\Command;

interface CommandHandler
{
}

<?php

declare(strict_types=1);

namespace App\Shared\Infrastructure\Bus\Command;

use ...

final class InMemoryCommandBus implements CommandBus
{
    private MessageBus $bus;

    public function __construct(
        iterable $commandHandlers
    ) {
        $this->bus = new MessageBus([
            new HandleMessageMiddleware(
                new HandlersLocator(
                    HandlerBuilder::fromCallables($commandHandlers),
                ),
            ),
        ]);
    }

    /**
     * @throws Throwable
     */
    public function dispatch(Command $command): void
    {
        try {
            $this->bus->dispatch($command);
        } catch (NoHandlerForMessageException $e) {
            throw new InvalidArgumentException(sprintf('The command has not a valid handler: %s', $command::class));
        } catch (HandlerFailedException $e) {
            throw $e->getPrevious();
        }
    }
}

Para la clase In Memory Command Bus, necesitaremos registrar cada controlador de comandos proveniente de la definición del servicio, nos beneficiaremos de una característica de Symfony llamada Service tags provistos desde el Service Container y el Autoconfiguration, nos permite etiquetar un servicio que luego podemos solicitar, en config/services.yaml indicamos el Service Container que deseamos etiquetar cada instancia de la interfaz Command Handler con la etiqueta internal.command_handler y luego declaramos nuestro In Memory Command Bus pasando todos los implementadores de Command Handler como un argumento iterable. El bus de comandos tomará cada controlador de comandos y declarará el comando esperado con el controlador adecuado.

parameters:

services:
    _defaults:
        autowire: true
        autoconfigure: true

    _instanceof:
        App\Shared\Domain\Bus\Command\CommandHandler:
            tags: ['internal.command_handler']
...
    ### Buses
    App\Shared\Domain\Bus\Command\CommandBus:
        class: App\Shared\Infrastructure\Bus\Command\InMemoryCommandBus
        arguments: [!tagged internal.command_handler]

Podemos crear una herramienta de creación de controladores que se encargue de buscar en la función __invoke del implementador del controlador de comandos y tomar el primer tipo de argumento como el comando necesario para llamar al controlador. En este punto, creamos una convención en la que cada controlador de comandos debe poder llamarse como función y tener solo un parámetro con el tipo de comando.

<?php

declare(strict_types=1);

namespace App\Shared\Infrastructure\Bus;

use ...

final class HandlerBuilder
{
    /**
     * @throws ReflectionException
     */
    public static function fromCallables(iterable $callables) : array
    {
        $callablesHandlers = [];

        foreach ($callables as $callable) {
            $envelop = self::extractFirstParam($callable);

            if (! array_key_exists($envelop, $callablesHandlers)) {
                $callablesHandlers[self::extractFirstParam($callable)] = [];
            }

            $callablesHandlers[self::extractFirstParam($callable)][] = $callable;
        }

        return $callablesHandlers;
    }

    /**
     * @throws ReflectionException
     */
    private static function extractFirstParam(object|string $class) : string|null
    {
        $reflection = new ReflectionClass($class);
        $method     = $reflection->getMethod('__invoke');

        if ($method->getNumberOfParameters() === 1) {
            return $method->getParameters()[0]->getClass()?->getName();
        }

        return null;
    }
}

Teniendo eso, podemos comenzar a construir nuestros comandos, por ejemplo:

<?php

declare(strict_types=1);

namespace App\EmailSender\Application\Create;

use ...

final class CreateEmailCommand implements Command
{
    public function __construct(
        private readonly string $sender,
        private readonly string $addressee,
        private readonly string $message,
    ) {
    }

    public function sender(): string
    {
        return $this->sender;
    }

    public function addressee(): string
    {
        return $this->addressee;
    }

    public function message(): string
    {
        return $this->message;
    }
}

Podemos crear un comando Create Email Command, contiene la información necesaria para crear un nuevo correo electrónico, pero no conoce el proceso necesario para eso.

<?php

declare(strict_types=1);

namespace App\EmailSender\Application\Create;

use ...

class CreateEmailCommandHandler implements CommandHandler
{
    public function __construct(private EmailRepository $repository)
    {
    }

    public function __invoke(CreateEmailCommand $command) : EmailId {
        $email = Email::createNewEmail(
            sender: new EmailAddress($command->sender()),
            addressee: new EmailAddress($command->addressee()),
            message: new Message($command->message()),
        );

        $this->repository->save($email);

        return $email->id();
    }
}

Creamos un Command Handler para el comando anterior, sabe que la función __invoke del objeto contiene un argumento único del tipo Create Email Command y conoce todos los procesos necesarios para crear un nuevo correo electrónico.

<?php

declare(strict_types=1);

namespace App\EmailSender\Infrastructure\Http;

use ...

class CreateEmailAction
{
    public function __construct(
        private readonly CreateEmailResponder $responder,
        private readonly CommandBus $commandBus,
    ) {
    }

    public function __invoke(Request $request) : Response
    {
        try {
            $this->commandBus->dispatch(
                new CreateEmailCommand(
                    sender: $request->request->get('sender'),
                    addressee: $request->request->get('addressee'),
                    message: $request->request->get('message'),
                ),
            );
        } catch (Exception $e) {
            $this->responder->loadError($e->getMessage());
        }

        return $this->responder->response();
    }
}

Entonces podemos inyectar fácilmente el Command Bus en una clase Action (Controller) y enviar el comando, la acción no sabe lo que sucede en el núcleo de la aplicación, pero el Command Bus puede asegurarse de que le enviaremos el comando a un Handler adecuado y realizará una acción. Tenga en cuenta que sabemos la acción que va a ocurrir, se proporciona a partir del nombre del comando.

QueryBus

Echemos un vistazo al modelo para un Query Bus. Podemos definir una arquitectura muy similar pero ahora necesitamos devolver un valor si estamos pidiendo algo con una consulta, necesitaremos introducir el concepto de Response. Una Response puede ser una colección de objetos de dominio o puede ser un solo objeto o cualquier cosa, quien puede determinar cuál es la Response es el Query Handler que sabe qué información necesita generar.

Entonces, terminamos con algo como esto:

<?php

declare(strict_types=1);

namespace App\Shared\Domain\Bus\Query;

interface Query
{
}

<?php

declare(strict_types=1);

namespace App\Shared\Domain\Bus\Query;

interface QueryBus
{
    public function ask(Query $query) : Response|null;
}

<?php

declare(strict_types=1);

namespace App\Shared\Domain\Bus\Query;

interface QueryHandler
{
}

<?php

declare(strict_types=1);

namespace App\Shared\Domain\Bus\Query;

interface Response
{
}

<?php

declare(strict_types=1);

namespace App\Shared\Infrastructure\Bus\Query;

use ...

final class InMemoryQueryBus implements QueryBus
{
    private MessageBus $bus;

    public function __construct(iterable $queryHandlers)
    {
        $this->bus = new MessageBus([
            new HandleMessageMiddleware(
                new HandlersLocator(
                    HandlerBuilder::fromCallables($queryHandlers),
                ),
            ),
        ]);
    }

    public function ask(Query $query): Response|null
    {
        try {
            /** @var HandledStamp $stamp */
            $stamp = $this->bus->dispatch($query)->last(HandledStamp::class);

            return $stamp->getResult();
        } catch (NoHandlerForMessageException $e) {
            throw new InvalidArgumentException(sprintf('The query has not a valid handler: %s', $query::class));
        }
    }
}

Podemos usar el mismo enfoque para registrar Query Handlers y Queries usando la herramienta para construir Handlers y sabiendo que tenemos un contrato donde la función __invoke necesita tener solo un argumento que debería ser un implementador de la interfaz Query.

Para obtener el valor de retorno de un Query Handler necesitamos usar Handled Stamp que marcará el mensaje como manejado y nos dará acceso al valor de retorno que en este punto sabemos que debería ser un implementador de Response.

En config/service.yaml podemos etiquetar cualquier instancia de Query Handler con internal.query_handler y dejar al Service Container inyectar todos los etiquetados al In Memory Query Bus.

services:
    _defaults:
        autowire: true 
        autoconfigure: true

    _instanceof:
        ...

        App\Shared\Domain\Bus\Query\QueryHandler:
            tags: ['internal.query_handler']
        ...
    ### Buses
    ...

    App\Shared\Domain\Bus\Query\QueryBus:
        class: App\Shared\Infrastructure\Bus\Query\InMemoryQueryBus
        arguments: [ !tagged internal.query_handler ]

Con todo en su lugar, podemos comenzar a crear Queries, por ejemplo:

<?php

declare(strict_types=1);

namespace App\EmailSender\Application\FindEmail;

use ...

final class FindEmailQuery implements Query
{
    public function __construct(private readonly int $id)
    {
    }

    public function id() : int
    {
        return $this->id;
    }
}

Una consulta simple que contiene el id del correo electrónico que estamos buscando se enviará al Find Email, un implementador de Query Handler. Tiene suficiente información sobre el correo electrónico para encontrarlo y puede generar una respuesta con la información necesaria.

<?php

declare(strict_types=1);

namespace App\EmailSender\Application\FindEmail;

use ...

final class FindEmail implements QueryHandler
{
    public function __construct(private EmailRepository $repository)
    {
    }

    public function __invoke(FindEmailQuery $query) : FindEmailResponse
    {
        $email = $this->repository->findById(
            EmailId::fromInt(
                $query->id(),
            ),
        );

        if ($email === null) {
            throw new InvalidArgumentException('Email unreachable');
        }

        return new FindEmailResponse(
            email: $email,
        );
    }
}

<?php

declare(strict_types=1);

namespace App\EmailSender\Application\FindEmail;

use ...

final class FindEmailResponse implements Response
{
    public function __construct(private readonly EmailDto $email)
    {
    }

    public function email() : EmailDto
    {
        return $this->email;
    }
}

Finalmente, podemos usar Query Bus en cualquier clase de Acción

<?php

declare(strict_types=1);

namespace App\EmailSender\Infrastructure\Http;

use ...

class GetEmailAction
{
    public function __construct(
        private GetEmailResponder $responder,
        private QueryBus $queryBus,
    ) {
    }

    public function __invoke(Request $request, int $id) : Response
    {
        try {
            /** @var FindEmailResponse $findEmailResponse */
            $findEmailResponse = $this->queryBus->ask(
                new FindEmailQuery(id: $id)
            );

            $email = $findEmailResponse->email();

            $this->responder->loadEmail($email);
        } catch (Exception $e) {
            $this->responder->loadError($e->getMessage());
        }

        return $this->responder->response();
    }
}

Nuevamente, la Acción sabe lo que está buscando pero no conoce el proceso completo para obtenerlo.

Conclusion

Podemos implementar fácilmente un patrón CQRS con componentes de Symfony creando buses de mensajes personalizados y definiendo un modelo que se puede reutilizar a lo largo de la aplicación. CQRS puede ayudarnos a separar las operaciones y las inquietudes de búsqueda en clases descriptivas de Command/Query para crear procesos mejor aislados, lo que hace que las clases estén abiertas a cambios.

See the code on

AdGARAY / cqrs-symfony

CQRS example with Symfony Messenger

CQRS with Symfony Messenger

Requirements

Docker compose

Setup

Initialize containers

$ docker compose up -d

Enter into the php container

$ docker compose exec -it php bash

Install composer dependencies

/var/www/html# $ composer install

Run migrations

/var/www/html# $ php bin/console doctrine:migrations:migrate --no-interaction

Go to localhost:8080

The php image already have xDebug listening on port 9003 with server name serverName=application if you want to go step by step

See the full post on dev.to/adgaray and the spanish version

View on GitHub

CQRS with Symfony Messenger

Adrian Garay — Mon, 22 Aug 2022 16:30:00 +0000

Ve la versión en español

CQRS con Symfony Messenger (Español)

Adrian Garay ・ Aug 22 '22

#php #cqrs #symfony

Introduction

Habitually we use the same data structure for writing and querying information on a system, for larger systems this can cause bigger data structures because it needs to integrate read and write in the same model. For example, when writing information we may need a lot of validations in order to ensure the information that we are persisting is correct, asking for this information can be different and complex in order to retrieve filtered data or different data structures for each case.

CQRS is a pattern that separates read and update operations for a data store. Implementing CQRS in your application can maximize its performance, scalability, and security. The flexibility created by migrating to CQRS allows a system to better evolve over time and prevents update commands from causing merge conflicts at the domain level.

The pattern

CQRS separates the read structure using queries in order to read data and the write model using commands to make operations with the data

Commands should be task-based, which means that we need to focus on the operation of the command, for example, on a delivery app when ordering something we will name the operation OrderProductCommand instead of AddProductToClient or CreateNewOrderProduct this also makes our application layer more consistent
Queries never modify the database. A query returns a DTO that does not encapsulate any domain knowledge. We need to focus on the information needed not on the domain behavior.

Benefits

Independent scaling. It allows the read and write models to scale independently
Optimized data schemas. The read model can use a schema that is optimized for queries, and the write model uses a schema that is optimized for updates.
Security. It's easier to ensure that only the right domain entities are performing writes.
Separation of concerns. The complex business logic goes into the write model. The read model can be simple.

Implement CQRS with a Symfony Messenger

The messenger component helps applications send and receive messages to/from other applications or via message queues. It also allows us to define custom message buses defining message types and handlers.

Let's talk about the software architecture.

CommandBus

Talking about commands we need to modulate a common interface that a message bus can manage and transport to handlers, the Command interface ends up being our base interface for each command. Each Command Handler implementor is going to make operations with the command given but the command itself doesn’t know what operation is performed. Also, we are going to create an interface for the Command Bus in order to create different kinds of Transporters for our messages (commands), in this case, we create one In Memory Command Bus but we can extend this concept easily if needed (ex: A queued work).

We will arrive with something like this on the src code of our Symfony application.

<?php

declare(strict_types=1);

namespace App\Shared\Domain\Bus\Command;

interface Command
{
}

<?php

declare(strict_types=1);

namespace App\Shared\Domain\Bus\Command;

interface CommandBus
{
    public function dispatch(Command $command) : void;
}

<?php

declare(strict_types=1);

namespace App\Shared\Domain\Bus\Command;

interface CommandHandler
{
}

<?php

declare(strict_types=1);

namespace App\Shared\Infrastructure\Bus\Command;

use ...

final class InMemoryCommandBus implements CommandBus
{
    private MessageBus $bus;

    public function __construct(
        iterable $commandHandlers
    ) {
        $this->bus = new MessageBus([
            new HandleMessageMiddleware(
                new HandlersLocator(
                    HandlerBuilder::fromCallables($commandHandlers),
                ),
            ),
        ]);
    }

    /**
     * @throws Throwable
     */
    public function dispatch(Command $command): void
    {
        try {
            $this->bus->dispatch($command);
        } catch (NoHandlerForMessageException $e) {
            throw new InvalidArgumentException(sprintf('The command has not a valid handler: %s', $command::class));
        } catch (HandlerFailedException $e) {
            throw $e->getPrevious();
        }
    }
}

For the In Memory Command Bus class we will need to register each Command Handler coming from the service definition, we will profit from a Symfony feature named Service tags provided from the Service Container and the Autoconfiguration, it allows us to tag a service that we can ask for it later, in config/services.yaml we indicate the Service Container to tag each instance of the Command Handler interface with the tag internal.command_handler and later we declare our In Memory Command Bus passing all the implementors of Command Handler as an iterable argument. The Command Bus will take each Command Handler and declare the Command Expected with the appropriate Handler.

parameters:

services:
    _defaults:
        autowire: true
        autoconfigure: true

    _instanceof:
        App\Shared\Domain\Bus\Command\CommandHandler:
            tags: ['internal.command_handler']
...
    ### Buses
    App\Shared\Domain\Bus\Command\CommandBus:
        class: App\Shared\Infrastructure\Bus\Command\InMemoryCommandBus
        arguments: [!tagged internal.command_handler]

We can create a Handler Builder tool that is responsible for searching on the __invoke of the Command Handler implementor and take the first argument type as the command needed for calling the handler. At this point, we create a convention where each Command Handler needs to be callable and have only one parameter with the type of the Command.

<?php

declare(strict_types=1);

namespace App\Shared\Infrastructure\Bus;

use ...

final class HandlerBuilder
{
    /**
     * @throws ReflectionException
     */
    public static function fromCallables(iterable $callables) : array
    {
        $callablesHandlers = [];

        foreach ($callables as $callable) {
            $envelop = self::extractFirstParam($callable);

            if (! array_key_exists($envelop, $callablesHandlers)) {
                $callablesHandlers[self::extractFirstParam($callable)] = [];
            }

            $callablesHandlers[self::extractFirstParam($callable)][] = $callable;
        }

        return $callablesHandlers;
    }

    /**
     * @throws ReflectionException
     */
    private static function extractFirstParam(object|string $class) : string|null
    {
        $reflection = new ReflectionClass($class);
        $method     = $reflection->getMethod('__invoke');

        if ($method->getNumberOfParameters() === 1) {
            return $method->getParameters()[0]->getClass()?->getName();
        }

        return null;
    }
}

Having that, we can start building our commands, for example:

<?php

declare(strict_types=1);

namespace App\EmailSender\Application\Create;

use ...

final class CreateEmailCommand implements Command
{
    public function __construct(
        private readonly string $sender,
        private readonly string $addressee,
        private readonly string $message,
    ) {
    }

    public function sender(): string
    {
        return $this->sender;
    }

    public function addressee(): string
    {
        return $this->addressee;
    }

    public function message(): string
    {
        return $this->message;
    }
}

We can create a Create Email Command, it contains the information needed to create a new email but it doesn’t know the process needed for that.

<?php

declare(strict_types=1);

namespace App\EmailSender\Application\Create;

use ...

class CreateEmailCommandHandler implements CommandHandler
{
    public function __construct(private EmailRepository $repository)
    {
    }

    public function __invoke(CreateEmailCommand $command) : EmailId {
        $email = Email::createNewEmail(
            sender: new EmailAddress($command->sender()),
            addressee: new EmailAddress($command->addressee()),
            message: new Message($command->message()),
        );

        $this->repository->save($email);

        return $email->id();
    }
}

We create a handler for the previous Command, it knows that we will __invoke the object with a unique argument of type Create Email Command, and it knows all the processes needed for creating a new Email.

<?php

declare(strict_types=1);

namespace App\EmailSender\Infrastructure\Http;

use ...

class CreateEmailAction
{
    public function __construct(
        private readonly CreateEmailResponder $responder,
        private readonly CommandBus $commandBus,
    ) {
    }

    public function __invoke(Request $request) : Response
    {
        try {
            $this->commandBus->dispatch(
                new CreateEmailCommand(
                    sender: $request->request->get('sender'),
                    addressee: $request->request->get('addressee'),
                    message: $request->request->get('message'),
                ),
            );
        } catch (Exception $e) {
            $this->responder->loadError($e->getMessage());
        }

        return $this->responder->response();
    }
}

So we can easily inject the Command Bus in an Action (Controller) class and dispatch the command, the action doesn’t know what happens in the core of the application but the Command Bus can ensure that we will send the Command to a proper Handler and it will perform an action. Notice that we know the action that is going to happen, it is provided from the name of the command.

QueryBus

Let's take a look at the model for a Query Bus. We can define a very similar architecture but now we need to return a value if we are asking for something with a query, we will need to introduce the concept of Response. A Response can be a collection of domain objects or it can be a single object or anything, who can determine what is the Response is the Query Handler which knows what information it needs to generate.

Then, we end up with something like this:

<?php

declare(strict_types=1);

namespace App\Shared\Domain\Bus\Query;

interface Query
{
}

<?php

declare(strict_types=1);

namespace App\Shared\Domain\Bus\Query;

interface QueryBus
{
    public function ask(Query $query) : Response|null;
}

<?php

declare(strict_types=1);

namespace App\Shared\Domain\Bus\Query;

interface QueryHandler
{
}

<?php

declare(strict_types=1);

namespace App\Shared\Domain\Bus\Query;

interface Response
{
}

<?php

declare(strict_types=1);

namespace App\Shared\Infrastructure\Bus\Query;

use ...

final class InMemoryQueryBus implements QueryBus
{
    private MessageBus $bus;

    public function __construct(iterable $queryHandlers)
    {
        $this->bus = new MessageBus([
            new HandleMessageMiddleware(
                new HandlersLocator(
                    HandlerBuilder::fromCallables($queryHandlers),
                ),
            ),
        ]);
    }

    public function ask(Query $query): Response|null
    {
        try {
            /** @var HandledStamp $stamp */
            $stamp = $this->bus->dispatch($query)->last(HandledStamp::class);

            return $stamp->getResult();
        } catch (NoHandlerForMessageException $e) {
            throw new InvalidArgumentException(sprintf('The query has not a valid handler: %s', $query::class));
        }
    }
}

We can use the same approach for registering Query Handlers and Queries using the tool for building Handlers and knowing that we have a contract where the __invoke function needs to have just one argument that should be an implementor of the Query interface.

For getting the return value of a Query Handler we need to use the Handled Stamp that is going to mark the message as handled and give us access to the return value that at this point we know should be a Response implementor.

In the config/service.yaml we can tag any instance of Query Handler with internal.query_handler and let the Service Container inject all the tagged to the In Memory Query Bus.

services:
    _defaults:
        autowire: true 
        autoconfigure: true

    _instanceof:
        ...

        App\Shared\Domain\Bus\Query\QueryHandler:
            tags: ['internal.query_handler']
        ...
    ### Buses
    ...

    App\Shared\Domain\Bus\Query\QueryBus:
        class: App\Shared\Infrastructure\Bus\Query\InMemoryQueryBus
        arguments: [ !tagged internal.query_handler ]

All things in place, we can start creating Queries for example:

<?php

declare(strict_types=1);

namespace App\EmailSender\Application\FindEmail;

use ...

final class FindEmailQuery implements Query
{
    public function __construct(private readonly int $id)
    {
    }

    public function id() : int
    {
        return $this->id;
    }
}

A simple query containing the id of the email that we are looking for is going to be sent to the Find Email, an implementor for Query Handler. It has enough information about the email for finding it and it can build a response with the information needed.

<?php

declare(strict_types=1);

namespace App\EmailSender\Application\FindEmail;

use ...

final class FindEmail implements QueryHandler
{
    public function __construct(private EmailRepository $repository)
    {
    }

    public function __invoke(FindEmailQuery $query) : FindEmailResponse
    {
        $email = $this->repository->findById(
            EmailId::fromInt(
                $query->id(),
            ),
        );

        if ($email === null) {
            throw new InvalidArgumentException('Email unreachable');
        }

        return new FindEmailResponse(
            email: $email,
        );
    }
}

<?php

declare(strict_types=1);

namespace App\EmailSender\Application\FindEmail;

use ...

final class FindEmailResponse implements Response
{
    public function __construct(private readonly EmailDto $email)
    {
    }

    public function email() : EmailDto
    {
        return $this->email;
    }
}

Finally, we can use the Query Bus in any Action class

<?php

declare(strict_types=1);

namespace App\EmailSender\Infrastructure\Http;

use ...

class GetEmailAction
{
    public function __construct(
        private GetEmailResponder $responder,
        private QueryBus $queryBus,
    ) {
    }

    public function __invoke(Request $request, int $id) : Response
    {
        try {
            /** @var FindEmailResponse $findEmailResponse */
            $findEmailResponse = $this->queryBus->ask(
                new FindEmailQuery(id: $id)
            );

            $email = $findEmailResponse->email();

            $this->responder->loadEmail($email);
        } catch (Exception $e) {
            $this->responder->loadError($e->getMessage());
        }

        return $this->responder->response();
    }
}

Again, the Action knows what is it looking for but it doesn’t know the complete process for getting it.

Conclusion

We can easily implement a CQRS pattern with components of Symfony making custom Message Buses and defining a model that can be reused along the app. CQRS can help us to separate operations and searching concerns into descriptive Command/Query classes for building better-isolated processes making classes open for changes.

See the code on

AdGARAY / cqrs-symfony

CQRS example with Symfony Messenger

CQRS with Symfony Messenger

Requirements

Docker compose

Setup

Initialize containers

$ docker compose up -d

Enter into the php container

$ docker compose exec -it php bash

Install composer dependencies

/var/www/html# $ composer install

Run migrations

/var/www/html# $ php bin/console doctrine:migrations:migrate --no-interaction

Go to localhost:8080

The php image already have xDebug listening on port 9003 with server name serverName=application if you want to go step by step

See the full post on dev.to/adgaray and the spanish version

View on GitHub

Lo básico en GraphQL

Adrian Garay — Fri, 28 May 2021 19:31:23 +0000

Introducción

GraphQL es un lenguaje de consultas para una API, usa un sistema de tipos que definen tu información y se ejecuta del lado del servidor. No está ligado a una base de datos o algún sistema de almacenamiento de la información y en su lugar es manejado por el código que lo define.

Se basa en la definición de tipos que permita consultar fields específicos de objetos y resolver la información requerida en la consulta.

Fields

# Type
type Car {
    model: String!
    manufacturer: String!
}

# Query
{
    car {
        model
        manufacturer
    }
}

# Data resolved
{
    "data": {
        "car": {
            "model": "97"
            "manufacturer": "Ford"
        }
    }
}

En el ejemplo anterior tenemos una query en GraphQL que necesita un objeto car que contiene dos fields: model y manufacturer. Un field en resumen es todo aquello que no es un objeto y es de tipo Scalar, en este caso los fields dentro de car resuelven en valores Scalar de tipo String.

El único objeto en este servicio es car compuesto por fields y definido como un type en la parte inicial de la query. Para el contexto de este servicio car es un type object que contiene dos fields que lo componen. De esta manera podemos escribir una consulta que revisa dentro del objeto car y regresa ambos fields.

Scalar Types

Ya que GraphQL se basa en la definición de tipos nos provee algunos valores de tipo Scalar. Estos valores son tipos que permiten resolver la informacion a un valor concreto por ejemplo:

Int: enteros con signo de 32-bit
Float: números con signo y punto flotante
String: secuencia de caracteres UTF-8
Boolean: true o false
ID: Este Scalar Type representa un identificador único del objeto, este tipo se resuelve en un String

Nos provee de valores establecidos pero no esta cerrado a su definición, algunos servicios de GraphQL te permiten crear tus propios Scalar Types con la condición que cada uno tiene que tener definida la manera de serializar y deserializar la informacion para comunicarse entre el código que lo define y el que lo consulta.

Arguments

A primera vista GraphQL parece un buen lenguaje para la obtención de datos pero los argumentos proveen una forma de consultar la información de manera concreta.

{
    car(id: "10"): {
        model
        manufacturer
    }
}

Cada objeto puede tener cero o n numero de argumentos. En el ejemplo anterior a través de un argumento id permite filtrar la informacion resuelta a solo aquellos car que tienen el id 10

Aliases

Al realizar consultas puede que necesites una manera de identificar la información que regresa la consulta. Esto es simple con el uso de aliases en la consulta.

{
    fordCars: car(manufacturer: "ford") {
        model
        manufacturer
    }
    nissanCars: car(manufacturer: "nissan") {
        model
        manufacturer
    }
}

{
    "data": {
        "fordCars": [
            {
                "model": "97",
                "manufacturer": "ford"
            }
        ],
        "nissanCars": [
            {
                "model": "2010",
                "manufacturer": "nissan"
            }
        ]
    }
}

Así los aliases se pueden agregar antes de la consulta y especificar el nombre de la entrada que tendrá. Los alias también pueden ser usados en fields para renombrar la llave de salida de la información.

Fragments

Cuando la consulta se convierte en algo repetitivo necesitamos una manera de simplificarlo, para esto tenemos la ayuda de los fragments que como su nombre indica son fragmentos de tipos. Los fragmentos nos permiten encapsular una parte del tipo de dato que necesitamos y de esta manera podemos realizar la misma petición de datos en distintas consultas.

fragment carInformation on Car {
    model
    manufacturer
}

{
    fordCars: car(manufacturer: "ford") {
        ...carInformation
    }
    nissanCars: car(manufacturer: "nissan") {
        ...carInformation
    }
}

Variables

La mayoría de las veces necesitarás consultar la información de manera dinámica, por ejemplo la siguiente consulta estática:

query CarByFord {
    fordCars: car(manufacturer: "ford") {
        model
        manufacturer
    }
}

Le llamamos estática debido a que la información que los autos que obtendremos serán siempre del fabricante ford, si necesitaramos consultar aquellos que sean del fabricante nissan tendríamos que escribir una consulta nueva. Bueno vamos a realizar algunas modificaciones.

query CarByManufacturer($manufacturer: String!) {
    car(manufacturer: $manufacturer) {
        model
        manufacturer
    }
}

De esta manera al ejecutar la query y enviarle la variable $manufacturer esta pasara como argumento en la consulta y permitirá hacer un filtrado dinámico de la informacion.

Si necesitaramos obtener siembre aquellos del fabricante ford y solo nissan si es requerido podríamos usar una variable default.

query CarByManufacturer($manufacturer: String = "ford") {
    car(manufacturer: $manufacturer) {
        model
        manufacturer
    }
}

En caso de no proporcionar la variable por defecto nos regresaría aquellos del fabricante ford.

Directives

Como pudimos observar las variables nos evitan el escribir mas consultas realizar alguna concatenación en nuestra consulta. De igual forma contamos con las directivas que brinda soporte a la modificación dinámica de la estructura de datos que la query va a resolver.

query CarByManufacturer($manufacturer: String = "ford", $includeManufacturer: Bool = false) {
    car(manufacturer: $manufacturer) {
        model
        manufacturer @include(if: $includeManufacturer)
    }
}

Si ejecutamos la query con las siguiente variables obtendremos un arreglo de car con registro del fabricante nissan pero sin incluir el nombre del fabricante debido al valor por defecto de $includeManufacturer es false y la directiva @include modifica la informacion de salida.

# Variables
{
    "manufacturer": "nissan"
}

# Data resolved
{
    "data": {
        "car": [
            {
                "model": "2010"
            }
        ]
    }
}

Ahora con la directiva @skip el field manufacturer sera skipeado solo si $includeManufacturer es true

query CarByManufacturer($manufacturer: String = "ford", $excludeManufacturer: Bool = false) {
    car(manufacturer: $manufacturer) {
        model
        manufacturer @skip(if: $excludeManufacturer)
    }
}

# Variables
{
    "manufacturer": "nissan"
}

# Data resolved
{
    "data": {
        "car": [
            {
                "model": "2010",
                "manufacturer": "nissan"
            }
        ]
    }
}

Mutations

Hasta el momento vimos cómo podemos obtener datos pero GraphQL también soporta la modificación de datos. La mayoría de request en API Rest permite la modificación de datos aun cuando se usa el método GET, por convención no se debe de usar este método en una acción que detone la modificación de datos por ello se usa POST para la creación y PUT/PATCH para la actualización. En GraphQL cualquier operación que realice la modificación de datos por convención debería de ser enviada especificando que se trata de una Mutation.

mutation CreateNewCar($model: String!, $manufacturer: String!) {
    createCar(model: $model, manufacturer: $manufacturer) {
        model,
        manufacturer
    }
}

Una mutation podría regresar los datos del objeto que fue creado por lo que a su vez podemos preguntar por cualquiera de los fields del objeto que acabamos de crear.

Pros y contras

Ventajas:

Se basa en la definición de tipos, al tener los tipos bien definidos esto puede reducir el error de comunicación entre el cliente y el servidor.
Provee una entrada única a la API, por lo que el cliente tiene mayor flexibilidad para realizar peticiones y modificaciones desde la misma.
Al tener tipos definidos se puede realizar una petición de los tipos de datos definidos.
Permite una buena escalabilidad de la API.

Desventajas:

Además de crear el código sólido de backend los desarrolladores también tienen que crear buenos esquemas de información que sean faciles de mantener.
La curva de aprendizaje para aquellos que están acostumbrados a trabajar con API Rest es alta.
Gran parte del procesamiento de las consultas se realiza en el servidor.
Migrar de una API Rest a GraphQL suele ser dificil y bastante caro.

Conclución

Definitivamente la flexibilidad que proporciona GraphQL para la comunicación entre el backend y frontend permite un desarrollo rápido de aplicaciones cliente-servidor. El backend se encarga enteramente de proveer la definición de tipos y el cómo estos se resuelven y el frontend solo tiene que preocuparse por saber qué información puede requerir y entonces realizar queries desde el mismo cliente. Además, al tener un solo punto de entrada para la realización de queries el cliente puede olvidarse completamente de la definición de urls y usar una unica conexion al servidor para realizar peticiones.

Está claro que esta tecnología nacida en el 2012 aún necesita alcanzar cierta madurez que permita a las empresas tomar en cuenta la migración a esto tipo de API.

Fuentes

A query language for your API

Dockerizar un proyecto Django

Adrian Garay — Sun, 25 Apr 2021 19:39:52 +0000

Introduccion

Docker es una herramienta que como desarrolladores debemos estar dispuestos a aprender nos permite hacer el despliegue de nuestras aplicaciones de una manera rápida y sencilla ademas de hacer que nuestros proyectos sean fáciles de distribuir. A continuación vamos a descubrir como dockerizar nuestra app en Django.

Elegir nuestras imágenes y el espacio de trabajo

Lo primero es saber que imágenes necesitamos y para ello lo primero es una imagen de con la que podremos usar el lenguaje.

python - Docker Hub

Lo siguiente es una imagen para montar nuestra base de datos, para este ejercicio decidí usar mysql en su versión 5.7

mysql

Creamos una carpeta la cual va a contener nuestro proyecto

~/ $ mkdir dockerproject
~/ $ cd dockerproject
~/dockerproject $

Definir dependencias

Para nuestro proyecto en Django necesitamos las librerías correspondientes ademas del interpretador de lenguaje Python, asi que necesitamos definir las dependencias de nuestro proyecto.

Creamos un archivo de nombre requirements.txt en nuestro espacio de trabajo el cual tiene que contener la versión de Django que vamos a usar y el cliente para mysql.

Django>=3.0,<4.0
mysqlclient>=2.0

El cliente de mysql es necesario ya que no se encuentra en las librerías por defecto para la versión 3 de Python, asi que lo agregaremos manualmente.

Nuestro servidor de Python

Dentro de la carpeta vamos a crear un archivo de nombre Dockerfile, esta sera nuestra imagen local de Python en la cual podremos definir una serie de instrucciones necesarias para el inicio de nuestro proyecto.

Definimos la imagen base.

FROM python:3

Creamos nuestro directorio de trabajo.

WORKDIR /code

Ahora necesitaremos instalar Django y el cliente de mysql para Python, en este paso usaremos el archivo de requirements.

COPY requirements.txt /code/

En este punto podemos instalar las dependencias con la siguiente instrucción.

RUN pip install -r requirements.txt

Y poner una copia de nuestro código en la carpeta en la que nos encontramos dentro de nuestro directorio de trabajo en el contenedor de Docker

COPY . /code/

Al final deberíamos de tener un archivo como el siguiente Dockerfile

FROM python:3

WORKDIR /code

COPY requirements.txt /code/

RUN pip install -r requirements.txt

COPY . /code/

Con el siguiente comando en la terminal podemos comprobar que nuestra imagen se puede procesar correctamente.

~/dockerproject $ docker build .
[+] Building 0.4s (10/10) FINISHED
 => [internal] load build definition from Dockerfile                                                       0.0s
 => => transferring dockerfile: 31B                                                                        0.0s
 => [internal] load .dockerignore                                                                          0.0s
 => => transferring context: 2B                                                                            0.0s
 => [internal] load metadata for docker.io/library/python:3                                                0.0s
 => [1/5] FROM docker.io/library/python:3                                                                  0.0s
 => [internal] load build context                                                                          0.1s
 => => transferring context: 2.43kB                                                                        0.0s
 => CACHED [2/5] WORKDIR /code                                                                             0.0s
 => CACHED [3/5] COPY requirements.txt /code/                                                              0.0s
 => CACHED [4/5] RUN pip install -r requirements.txt                                                       0.0s
 => CACHED [5/5] COPY . /code/                                                                             0.0s
 => exporting to image                                                                                     0.1s
 => => exporting layers                                                                                    0.0s
 => => writing image sha256:13e36e422c69799feb5105373d4b04d78c683c7527294be29c80a7940a6374b4               0.0s

Ahora podemos comprobar que las dependencias se instalaron correctamente con el hash de la imagen que nos devuelve el comando anterior y con la siguiente instrucción. Si todo esta correcto Python debería de regresar la versión de Django instalada

~/dockerproject $ docker run 13e36e422c69799feb5105373d4b04d78c683c7527294be29c80a7940a6374b4 python -m django --version
3.2

Crear el proyecto

Para el siguiente paso podemos crear el proyecto desde nuestro contenedor asi que ejecutaremos el siguiente comando. El comando puede variar en el parámetro directorio-actual y el cual te dejo ejemplos para Linux y Windows.

~/dockerproject $ docker run -it --volume <directorio-actual>:/code <hash-de-la-imagen> python -m django startproject dockerproject .

Windows $ docker run -it --volume %cd%:/code <hash-de-la-imagen> python -m django startproject dockerproject .
Linux $ docker run -it --volume $(pwd):/code <hash-de-la-imagen> python -m django startproject dockerproject .

Al finalizar obtendremos un nuevo directorio con el nombre del proyecto que contiene los archivos de configuración del proyecto y un archivo de nombre manage.py que nos permitirá ejecutar comando de Django de nuestro proyecto.

Ahora tenemos que decirle a Django que conexión de base de datos va a usar y esto lo podremos hacer con el archivo de configuración /dockerproject/setting.py en la linea 76 con la constante DATABASES.

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'project',
        'USER': 'root',
        'PASSWORD': 'password',
        'HOST': 'docker_python_db',
        'PORT': 3306
    }
}

Docker compose

Para una gestión mas limpia de los contenedores de nuestro proyecto usaremos docker compose.

Creamos el archivo docker-compose.yml en el cual definiremos los servicios para nuestro proyecto.

Primero definimos que versión de compose vamos a usar.

version: '3.8'

Después definimos los servicios que vamos a usar, en primer lugar nuestro servidor web.

# version
web:
    container_name: ${PROJECT_NAME}_web
    build: .
    working_dir: /code
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/code
    ports:
      - '8085:8000'
    expose:
      - '8000'
    links:
      - mysql
    networks:
      backend:
        ipv4_address: 192.20.0.5

Explicando un poco la definición de este servicio vamos a poner como nombre del contenedor el nombre del proyecto mas la terminación _web. El contenedor se va a genera desde el contexto del mismo directorio en el cual se encuentra nuestra imagen en Dockerfile. El directorio de trabajo sera /code y el comando que se estará ejecutando el cual va a ser:

command: python manage.py runserver 0.0.0.0:8000

Este comando iniciara el servidor de test que provee Django, este sera el comando que se estará ejecutando en el ciclo de vida del contenedor. Después con volumes vamos a pedir a Docker compose que cree una copia de nuestro directorio dentro del directorio de trabajo del contenedor y esto nos servirá para la ejecución del código en el contenedor.

Con ports le indicaremos el mapa de puertos de nuestro host y el contenedor, en este caso mapeamos el puerto 8085 de nuestro host al puerto 8000 del contenedor y el cual es usado para el servidor.

La instrucción expose nos permite agregar metadata que para saber en que puerto se estará publicando la aplicación.

La instrucción links nos permite ligar a otro servicio el que se esta definiendo, en otras palabras nos permite definir que el servicio web va a interactuar con mysql.

Finalmente networks define la red por la cual se comunicaran los diferentes servicios. En esta parte especificamos una dirección ip fija.

Ahora podemos añadir el servicio de mysql para nuestra base de datos.

# web
mysql:
    container_name: ${PROJECT_NAME}_db
    image: 'mysql:5.7'
    volumes:
      - './database/data:/var/lib/mysql'
    ports:
      - '3308:3306'
    networks:
      backend:
        ipv4_address: 192.20.0.6
    environment:
      MYSQL_DATABASE: project
      MYSQL_ROOT_PASSWORD: password

Aquí definimos el nombre del contenedor, que usa la imagen mysql:5.7 y que estará montando un volume de la carpeta ./database/data en /var/lib/mysql este paso nos permitirá mantener la base de datos que se cree en el contenedor de mysql y asi no tendremos que definir la base de datos cada que iniciamos los servicios. Mapeamos el puerto 3308 al 3306 que usa mysql en el contenedor y definimos la red a la que estará conectada con su respectiva ip. Finalmente para el contenedor de mysql podemos definir dos variables de entorno MYSQL_DATABASE nos permite definir la base de datos que se creara cuando el servicio inicie y ademas MYSQL_ROOT_PASSWORD que define la contraseña del usuario root.

Como ultimo con docker-compose definimos la red backend que se uso en los servicios anteriores. La red backend usara el driver bridge y una configuración donde las direcciones ip tendrán una mascara de 24 y empezaran con 192.20.0.

# version
# services
networks:
  backend:
    driver: bridge
    ipam:
      config:
        - subnet: 192.20.0.0/24

Al final tendrías un archivo docker-compose.yml como el siguiente:

version: '3.8'

services:

  web:
    container_name: ${PROJECT_NAME}_web
    build: .
    working_dir: /code
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/code
    ports:
      - '8085:8000'
    expose:
      - '8000'
    links:
      - mysql
    networks:
      backend:
        ipv4_address: 192.20.0.5

  mysql:
    container_name: ${PROJECT_NAME}_db
    image: 'mysql:5.7'
    volumes:
      - './database/data:/var/lib/mysql'
    ports:
      - '3308:3306'
    networks:
      backend:
        ipv4_address: 192.20.0.6
    environment:
      MYSQL_DATABASE: project
      MYSQL_ROOT_PASSWORD: password

networks:
  backend:
    driver: bridge
    ipam:
      config:
        - subnet: 192.20.0.0/24

Necesitamos definir nuestra variable de entorno para el nombre del proyecto. Para esto creamos un archivo .env en nuestro directorio de trabajo el cual tiene que contener lo siguiente:

###< docker ###
PROJECT_NAME=docker_python
###> docker ###

Para comprobar que todo funciona correctamente iniciando los servicios con el comando:

~/dockerproject $ docker-compose up -d

Si todo esta correcto al ir a nuestro navegador e introducir localhost:8085 podremos ver una pantalla como la siguiente:

Migraciones

Como ultimo podemos correr las migraciones en la base de datos, estas migraciones serán las migraciones del modulo admin de Django, para este paso podremos usar el siguiente comando:

~/dockerproject $ docker exec -it docker_python_web bash

El cual ejecuta el comando bash en el contenedor web, desde el que podremos ejecutar las migraciones con:

root@<hash>: /code# python manage.py migrate

Conclusion

Docker es siempre una excelente opción para la distribución de nuestras aplicaciones, podemos personalizar una imagen local y adecuarla a nuestras necesidades, ademas con solo instalar Docker tendremos una serie de herramientas poderosas para un desarrollo mas rápido y en este caso sin tener que instalar Python directamente en nuestra computadora podremos iniciar un proyecto en Django.

Puedes consultar el código en:

DEV Community: Adrian Garay

CQRS con Symfony Messenger (Español)

CQRS with Symfony Messenger

Adrian Garay ・ Aug 22 '22

Introducción

El patrón de diseño

Beneficios

Implementar CQRS con Symfony Messenger

CommandBus

QueryBus

Conclusion

AdGARAY / cqrs-symfony

CQRS example with Symfony Messenger

CQRS with Symfony Messenger

Requirements

Setup

CQRS with Symfony Messenger

CQRS con Symfony Messenger (Español)

Adrian Garay ・ Aug 22 '22

Introduction

The pattern

Benefits

Implement CQRS with a Symfony Messenger

CommandBus

QueryBus

Conclusion

AdGARAY / cqrs-symfony

CQRS example with Symfony Messenger

CQRS with Symfony Messenger

Requirements

Setup

Lo básico en GraphQL

Introducción

Fields

Scalar Types

Arguments

Aliases

Fragments

Variables

Directives

Mutations

Pros y contras

Conclución

Fuentes

Dockerizar un proyecto Django

Introduccion

Elegir nuestras imágenes y el espacio de trabajo

Definir dependencias

Nuestro servidor de Python

Crear el proyecto

Docker compose

Migraciones

Conclusion

AdGARAY / docker-python

This is a skeleton for dockerized python project