CQRS and Domain

CQRS means Command Query Responsibility Segregation: the model that changes data (commands) is separated from the model that reads it (queries). PrestaShop did not adopt it for performance. The reason, stated in the project’s architecture decision records and developer documentation, is migration: while the back office moved page by page from legacy controllers to Symfony, the new pages needed a way to read and change data without calling ObjectModel classes such as Product or Category directly, and without creating a second source of truth next to them. Commands and queries are that boundary. A controller knows only the command class and its constructor arguments; whether the handler behind it uses an ObjectModel today or Doctrine tomorrow is invisible to the caller.

Three practical benefits follow, and they are visible in 9.2.

The cost is boilerplate: a single operation is at least a command, a handler and (for creations) an id value object. The core accepts that cost for its own pages; a module that only needs to save one setting does not have to use CQRS, and the module pages show the lighter alternatives. Use it when the operation will be called from more than one place, when it has rules worth testing, or when you want it in the Admin API.

The core groups everything by domain: 9.2.0 has 58 domain folders under src/Core/Domain that contain commands or queries (Product, Order, Customer, Cart, Shipment, Category, Carrier, Tax rules group, Address, Attribute group and so on), each with the same sub-folder layout (Command, CommandHandler, Exception, Query, QueryHandler, QueryResult, ValueObject). Copying that layout in a module keeps the code recognizable to anyone who has read the core.

Two rules of the core are worth stating because they are what make the pattern useful. Every constructor validates, so there is no "invalid command" state to check later; and a command or query receives primitive types (int, float, string, bool, array) or value objects rather than entities, so it can be built from a form, a JSON body or a CLI argument alike.

A bus maps a command or query class to its handler. PrestaShop exposes two services with the same interface, PrestaShop\PrestaShop\Core\CommandBus\CommandBusInterface and its single method handle($message).

The distinction between the command bus and the query bus is therefore conventional: in 9.2.0 both services wrap the same Symfony Messenger bus, messenger.bus.default, configured in app/config/messenger.yml with a single middleware, PrestaShopBundle\CommandBus\Middleware\CommandRegisterMiddleware, which records every executed command in an ExecutedCommandRegistry (it feeds the CQRS panel of the Symfony debug toolbar and profiler). The Messenger defaults apply: allow_no_handlers is false and allow_no_senders is true, there are no transports and no routing, so messages are handled synchronously in the same process.

debug:messenger is the most useful command for a module developer: it lists every message class the bus can dispatch and the handler service that receives it, including the handlers of installed modules. On the checked installation it listed 517 handler entries in total, among them the Symfony ones (RunProcessMessage, SendEmailMessage) next to the core and module handlers.

MessengerCommandBus::handle() delegates to Messenger’s HandleTrait, which returns the handler’s result, and it unwraps HandlerFailedException: when a handler throws, the caller receives the handler’s original exception (the domain exception), not Messenger’s wrapper. The module example below relies on it, and the console command catches its own RoastDateException type outside the bus. A message that no handler accepts raises Messenger’s own exception; in the checked installation, handling a stdClass produced a NoHandlerForMessageException from the Symfony Messenger component with the message No handler for message "stdClass"., and that exception is not wrapped. Symfony’s HandleTrait, which the bus uses to return the handler’s result, expects exactly one handler and raises a LogicException when a message was handled several times (Symfony behaviour that was not exercised here), so keep one handler per message.

Before 9.0 PrestaShop implemented the bus with the Tactician library and a league/tactician-bundle configuration. Tactician was removed in 9.0 together with Guzzle and SwiftMailer, and the 9.2.0 composer.lock contains no Tactician package. The developer documentation page on CQRS still says the bus is implemented with Tactician in its section on the buses; that sentence describes 8.x and older, and the page’s code examples are otherwise current.

Source: PrestaShop devdocs: CQRS, commands and queries

The sequence below follows the Pocket Coffee example from a console command (a controller, a form data handler or an API operation looks the same from the bus onwards).

The console lists every command and query that has a registered handler, which turns the codebase into a catalogue of what the shop can do.

The options are --domain (-d, repeatable, an exact namespace segment such as Currency), --format (-f, regular or simple) and --hasApiEndpoint (1 to keep only the operations that the Admin API exposes, 0 for the others). The regular format prints, for each entry, a counter, Class:, Type: (Command or Query), an API: line with the HTTP operation when the Admin API exposes it, and the first line of the class docblock; the simple format prints the class name followed by OK or NOT OK according to whether an API endpoint exists.

On the checked installation the core contributed 506 entries, 371 commands and 135 queries, spread over 58 domains (the largest are Product with 76, Order with 26, Customer with 20 and Cart with 19), and 137 of them were exposed through the Admin API. The listing treats an entry as a Command when its fully qualified class name contains \Command\ and as a Query otherwise; the type is therefore a naming convention of the namespace, not a property of the class, and a command class placed outside a Command namespace is reported as a Query.

A module’s classes appear as soon as its handlers are registered: after installing the example module below, the listing included PocketCoffee\PcfbCqrs\Command\SetRoastDateCommand (Command) and PocketCoffee\PcfbCqrs\Query\GetRoastDate (Query), and --domain=PocketCoffee listed exactly those two. Use the first docblock line of every command and query, because it is what this command shows.

Source: PrestaShop devdocs: prestashop:list:commands-and-queries

The example is a complete module, pcfbcqrs (technical name in lowercase letters and digits, as the module rules require), with this layout. Every folder also contains the standard index.php redirect file, which is omitted from the listings.

Source: PrestaShop devdocs: CQRS, commands and queries

A new handler that never runs is almost always a registration mistake. The mechanism in 9.2 has four parts and each can be checked.

debug:container <HandlerClass> shows the tag and the handled class, and debug:messenger shows the final routing. The core’s own handlers are defined the same way (the tax creation handler is a service called prestashop.adapter.tax.command_handler.add_tax_handler that carries the same attribute), and its handler interface in Core\Domain is what a controller type-hints.

Two pitfalls are specific to modules. First, the services of a module are loaded from config/services.yml (or, from 9.2, the first existing of services.php, services-9.2.yml, services-9.yml and services.yml), and the back-office container is the one that holds the buses. The front-office container is a lighter one: on the checked installation, asking the front container for prestashop.core.command_bus or prestashop.core.query_bus answered that the service does not exist (as it did for router and translator, while doctrine.orm.entity_manager was available), and a module’s handler services are not loaded into it. A front-office hook that needs data owned by a handler must therefore read it with a plain class that it instantiates itself (the repository, for instance) or from a module front controller, not through the buses; the architecture page explains the two containers. Second, the CLI note of the developer documentation applies: legacy classes used inside a console command may need an initialized context. The roast-date handler uses Product::existsInDatabase and Db successfully from the console, but a handler that depends on the employee, the cart or the Smarty context needs the context helper described in the console documentation.

The core’s own value objects show what to model. ExchangeRate refuses a rate of zero or less with a currency constraint exception, so a service that receives an ExchangeRate needs no assertion of its own; TaxId wraps a positive integer; ShippingMethod and OutOfRangeBehavior wrap the small set of allowed integers of a carrier (BY_WEIGHT 1, BY_PRICE 2; USE_HIGHEST_RANGE 0, DISABLED 1) and throw when given anything else. On the output side, EditableTax carries the tax id (as a value object), the localized names, the rate and the active flag, and EditableCustomer does the same for a customer: a caller never has to ask whether a key exists. Both kinds are immutable, which makes them safe to cache and to pass between layers.

The domain exception hierarchy follows the same pattern. Each domain has a base exception (CategoryException, TaxException) that extends PrestaShop\PrestaShop\Core\Domain\Exception\DomainException, and specific subclasses such as CannotAddCategoryException or CategoryNotFoundException that a handler throws. A handler that wraps a legacy PrestaShopException translates it into a domain exception, so the upper layers never catch legacy types. This is also what lets the Admin API map exceptions to HTTP statuses, as shown next.

Source: PrestaShop devdocs: Value objects

An Admin API resource is a PHP class with the #[ApiResource] attribute whose operations name a command or a query. The Tax resource of the API resources module (ps_apiresources, 0.9.0 in 9.2.0) shows the pattern, reduced here to the creation operation.

The resource class is the API’s data shape (its public properties are the JSON fields, with Symfony validation constraints), the mapping arrays rename API fields to the constructor arguments of the command and back to the fields of the query result, scopes ties the operation to an OAuth scope, and exceptionToStatus turns a domain exception into an HTTP status. The serializer builds the command from the request body, sends it to the command bus and, for a creation, reads the resource back with the query. This is why the earlier POST /admin-api/taxes call, executed against the checked installation, created a tax through AddTaxCommand and its handler (AddTaxHandler, which validates the Tax ObjectModel and saves it) and answered {"taxId":3}, the id coming back as the handler’s value-object result, and why a request without a name in the default language is refused before any handler runs. A resource for the roast date follows the same shape with SetRoastDateCommand and GetRoastDate; the Admin API page shows how a module registers it.

Source: PrestaShop devdocs: Admin API, API resources

Back-office controllers and form data handlers receive the buses by injection and never create an ObjectModel themselves. Identifiable-object forms (the create and edit forms of the grid pages) pair a data provider that sends a query to fill the form with a data handler that sends a command on submit, so a migrated page contains no persistence code. The same holds for grid actions such as bulk delete: the controller sends one command per selected id, or a bulk command, and handles the typed exceptions to show the right flash message. The developer documentation walks through the contact form as the reference example, and the grid and forms page of this section shows how the pieces connect.

PrestaShop Recipes (2017) and the other 1.x books call ObjectModel classes directly from module code and from legacy controllers: new Product($id), setting properties and calling save(). That still works in 9.2 (the example’s repository uses Product::existsInDatabase and Db), but the books predate commands, queries and the Admin API. For new module code that changes shop data owned by the core, send the core’s own commands (EditTaxCommand, SetCarrierRangesCommand and the rest of the inventory) instead of editing core tables or objects yourself, because a command also runs the validation and the hooks that the domain defines.

The roast-date domain built here stays small on purpose: one command, one query, one value object and a table of its own. The next steps of the thread use it: the module pages add a hook that renders the badge from RoastDateInfo, a grid column and an edit field in the product page, an Admin API resource that exposes SetRoastDateCommand and GetRoastDate, and a front controller that shows the badge to customers without touching the back-office container.