Download the PHP package arkonsoft/ps-module-cqrs without Composer

PS Module CQRS

A lightweight CQRS (Command Query Responsibility Segregation) implementation for PrestaShop modules. Uses PHP 8 attributes to bind commands and queries to their handlers — no registry or convention-based resolution.

Table of Contents

• Description
• Requirements
• Installation
• Usage
  • Basic Setup
  • The HandledBy Attribute
  • Creating Commands and Handlers
  • Creating Queries and Handlers
  • Using the Buses
• Handler Resolution (callable)
• Error Handling
• Migration from Convention-Based Binding
• License
• Support

Description

This library provides a simple way to implement the CQRS pattern in PrestaShop modules. It includes CommandBus and QueryBus classes that resolve handlers at runtime by reading the #[HandledBy(HandlerClass::class)] attribute from the command or query class. There is no registry, no builder, and no naming convention — you pass a callable that creates handler instances (e.g. from your DI container or new $class()).

Requirements

• PHP >= 8.1
• PrestaShop >= 8.0.0

The library does not require any specific DI container. You provide a callable that resolves handler class names to instances.

Installation

Usage

Basic Setup

In your module's main class, create the buses by passing a callable that receives the handler class name (string) and returns the handler instance:

The HandledBy Attribute

Put the HandledBy attribute on the command or query class (not on the handler). It points to the handler class that will process that command or query.

• Command class: #[HandledBy(YourCommandHandler::class)]
• Query class: #[HandledBy(YourQueryHandler::class)]

The bus reads this attribute at runtime when you call handle(), so there is no registry to build or namespaces to scan.

Creating Commands and Handlers

Command — add the attribute with the handler class:

Handler — no attribute; just implement handle(Command $command):

Creating Queries and Handlers

Query — add the attribute with the handler class:

Handler — no attribute; just implement handle(Query $query):

Using the Buses

Handler Resolution (callable)

The constructor of CommandBus and QueryBus accepts a callable with signature (string $handlerClass): object. The bus calls it with the handler FQCN (from the HandledBy attribute) and uses the returned instance to call handle($command) or handle($query).

Examples:

With a PSR-11 or custom container:

Simple factory (no DI):

There is no HandlerResolverInterface or resolver class in the library — you pass the callable directly.

Error Handling

• If a command or query class does not have exactly one #[HandledBy(...)] attribute, the bus throws a \RuntimeException.
• Any exception thrown by your handler propagates from handle().

Migration from Convention-Based Binding

If you used an older version that resolved handlers by convention (e.g. CreateProductCommand → CreateProductHandler in a Handler namespace):

1. Add #[HandledBy(YourHandler::class)] to each command and query class.
2. Replace the container in the bus constructor with a callable:
   new CommandBus(fn(string $class) => $container->get($class))
   (and the same for QueryBus).
3. Remove any dependency on a specific DI library from this package; your module still uses its own container inside the callable.

No registry, builder, or handler list is required.

License

Commercial - The terms of the license are subject to a proprietary agreement between the author (Arkonsoft) and the licensee.

Support

For support and questions, please contact: [email protected]