lmc/cqrs-bundle

A symfony bundle for CQRS library and its extensions for Queries and Commands

2.1.0 2024-03-06 13:34 UTC

Requires

• php: ^8.2
• ext-json: *
• ext-mbstring: *
• lmc/cqrs-handler: ^2.2
• lmc/cqrs-types: ^3.2
• symfony/config: ^5.2 || ^6.0 || ^7.0
• symfony/console: ^5.2 || ^6.0 || ^7.0
• symfony/dependency-injection: ^5.2 || ^6.0 || ^7.0
• symfony/error-handler: ^5.2 || ^6.0 || ^7.0
• symfony/framework-bundle: ^5.2 || ^6.0 || ^7.0
• symfony/http-foundation: ^5.2 || ^6.0 || ^7.0
• symfony/http-kernel: ^5.2 || ^6.0 || ^7.0
• twig/twig: ^2.0 || ^3.0

Requires (Dev)

• ergebnis/composer-normalize: ^2.5
• lmc/coding-standard: ^3.3
• lmc/cqrs-http: ^3.1
• lmc/cqrs-solr: ^3.1
• php-parallel-lint/php-parallel-lint: ^1.2
• phpstan/extension-installer: ^1.1
• phpstan/phpstan: ^1.6
• phpstan/phpstan-phpunit: ^1.1
• phpunit/phpunit: ^11.0.4
• symfony/yaml: ^5.2 || ^6.0 || ^7.0

Suggests

• lmc/cqrs-http: Provides http handler and base types for queries and commands.
• lmc/cqrs-solr: Provides solr handler and base types for queries and commands.

MIT

README

Symfony bundle for CQRS libraries and extensions. It registers services, data collectors etc. by a configuration.

Table of contents

• Installation
• Configuration
  • Routes
  • Tags
• Services
  • Handlers
• Extensions
  • HTTP
  • Solr
• List of all predefined services

Installation

composer require lmc/cqrs-bundle

Configuration

lmc_cqrs:
    profiler: false         # Whether to enable profiler and allow profiling queries and commands [default false]
    debug: false            # Whether to enable debug the CQRS by a console command [default false]

    cache:
        enabled: false                          # Whether to use cache for Queries [default false (true, if you define cache_provider)]
        cache_provider: '@my.cache.provider'    # Service implementing a CacheItemPoolInterface. Required when cache is enabled [default null]

    extension:
        http: false         # Whether should http extension be active (requires a lmc/cqrs-http dependency) [default false]
        solr: false         # Whether should solr extension be active (requires a lmc/cqrs-solr dependency) [default false]

Profiler extended configuration

lmc_cqrs:
    profiler:
        enabled: false      # Whether to enable profiler and allow profiling queries and commands [default false]
        verbosity: ''       # Verbosity level (verbose or debug) for a profiler bag - empty string is a default for normal

TIPs:

• it is advised to set profiler: '%kernel.debug%' so it profiles (and registers all services for profiling) only when it is really used
• you can define profiler and debug in your dev/lmc_cqrs.yaml to only allow it in dev Symfony environment

Note: if you don't enable any of the extension, there will only be a CallbackQueryHandler and CallbackSendCommandHandler, so you probably need to register your own.

Routes

You must register the routes for a CQRS bundle if you enable a profiler.

# config/routes.yaml

lmc_cqrs_bundle_routes:
    resource: "@LmcCqrsBundle/Resources/config/routes.yaml"

Tags:

Tags are automatically registered, if your class implements an Interface and is registered in Symfony container as a service

• lmc_cqrs.query_handler (QueryHandlerInterface)
• lmc_cqrs.send_command_handler (SendCommandHandlerInterface)
• lmc_cqrs.profiler_formatter (ProfilerFormatterInterface)
• lmc_cqrs.response_decoder (ResponseDecoderInterface)

With priority

services:
    My\CustomQueryHandler:
        tags:
            - { name: 'lmc_cqrs.query_handler', priority: 80 }

Note: Default priority is 50 and none of the predefined handlers, profilers, etc. has priority higher than 90 (see complete list below)

Services

Bundle registers all necessary services according to configuration (for example, if you set http: true it will automatically register all http handlers, etc.)

Most of the services are registered both by an alias and a class name, so it will be available for autowiring. All interfaces are automatically configured to have a tag (see Tags section above).

Handlers

There are 2 main services, which are essential to the library. Both of them have its interface to represent it, and it is advised to use it via the interface.

1. Query Fetcher Interface

• implementation Lmc\Cqrs\Handler\QueryFetcher
• alias: @lmc_cqrs.query_fetcher
• it will find a handler for your query, handles it, decodes a response and caches the result (if cache is enabled)
• provides features:
  • caching
    • requires:
      • cache_provider (set in the configuration) - service implements Psr\Cache\CacheItemPoolInterface
      • Query to implement Lmc\Cqrs\Types\Feature\CacheableInterface
    • it allows to cache a decoded result and load it again from cache
  • profiling
    • requires:
      • enabled profiler (in the configuration)
      • Query to implement Lmc\Cqrs\Types\Feature\ProfileableInterface
    • it profiles a query, its execution time, response, applied handler and decoders and shows the info in the Symfony profiler

Fetching a query

You can do whatever you want with a response, we will persist a result into db, for an example or log an error.

// with continuation
$this->queryFetcher->fetch(
    $query,
    fn ($response) => $this->repository->save($response),
    fn (\Throwable $error) => $this->logger->critical($error->getMassage())
);

// with return
try {
    $response = $this->queryFetcher->fetchAndReturn($query);
    $this->repository->save($response);
} catch (\Throwable $error) {
    $this->logger->critical($error->getMessage());
}

2. Command Sender Interface

• implementation Lmc\Cqrs\Handler\CommandSender
• alias: @lmc_cqrs.command_sender
• it will find a handler for your command, handles it, decodes a response
• provides features:
  • profiling
    • requires:
      • enabled profiler (in the configuration)
      • Command to implement Lmc\Cqrs\Types\Feature\ProfileableInterface
    • it profiles a command, its execution time, response, applied handler and decoders and shows the info in the Symfony profiler

Sending a command

You can do whatever you want with a response, we will persist a result into db, for an example or log an error.

// with continuation
$this->commandSender->send(
    $command,
    fn ($response) => $this->repository->save($response),
    fn (\Throwable $error) => $this->logger->critical($error->getMassage())
);

// with return
try {
    $response = $this->commandSender->sendAndReturn($query);
    $this->repository->save($response);
} catch (\Throwable $error) {
    $this->logger->critical($error->getMessage());
}

Note: There is no logging feature in the CQRS library, if you need one, you have to implement it by yourself.

Profiler Bag

There is a profiler bag service, which is a collection of all profiler information in the current request. The information inside are used by a CqrsDataCollector, which shows them in the Symfony profiler.

It requires profiler: true in the configuration.

You can access the profiler bag either by:

• @lmc_cqrs.profiler_bag (alias)
• Lmc\Cqrs\Handler\ProfilerBag (autowiring)
• or access a CqrsDataCollector programmatically (see here)

Extensions

We offer a basic extensions for a common Commands & Queries

• Http (using PSR-7)
• SOLR (using Solarium)

Http

Http extension repository

Installation

composer require lmc/cqrs-http

NOTE: You will also need an implementation for PSR-7, PSR-17 and PSR-18 for HTTP extensions to work.

Configuration

lmc_cqrs:
    extension:
        http: true

Enabling a Http extension will allow a QueryFetcher and CommandSender to handle a PSR-7 Requests/Response and decode it.

Solr

SOLR extension repository

Installation

composer require lmc/cqrs-solr

Configuration

lmc_cqrs:
    extension:
        solr: true

Enabling a Solr extension will allow a QueryFetcher and CommandSender to handle a Solarium Requests/Result and decode it.

Solarium Query Builder

It allows you to build a Solarium request only by defining an Entity with all features you want to provide. See Solr extension readme for more information.

Note: You can specify a tag for your custom applicator by lmc_cqrs.solr.query_builder_applicator

List of all predefined services and their priorities

Note: To see a list of all services really registered in your application use bin/console debug:cqrs (it requires debug: true in your configuration)

Top most handlers for Commands & Queries

Query Handlers

Send Command Handlers

Response decoders

Profiler formatters

Other services