OpenParable
Skip to content
← Back to skills

Implement Cqrs Handlers

Development
implement-cqrs-handlers

Implement Cqrs Handlers is an Agent Skill for development published in the PrestaShop/PrestaShop repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Implement all command and query handlers in the Adapter layer. Each handler delegates to the repository for persistence — no direct SQL or ObjectModel access. Handlers use #[AsCommandHandler] / #[AsQueryHandler] attributes for auto-registration. Trigger: "implement handlers for {Domain}".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/PrestaShop/PrestaShop/blob/HEAD/.ai/Component/CQRS/skills/implement-cqrs-handlers/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/implement-cqrs-handlers, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

implement-cqrs-handlers

Handlers live in src/Adapter/{Domain}/CommandHandler/ and QueryHandler/. See CQRS/CONTEXT.md for conventions (#[AsCommandHandler]/#[AsQueryHandler] attributes, no cross-handler calls, return types).

1. Add handler

Add{Domain}Handler.php implementing Add{Domain}HandlerInterface:

  • Inject {Domain}Repository
  • handle(Add{Domain}Command $command): {Domain}Id:
    • Construct the ObjectModel entity from command data
    • For multilingual fields, map $command->getLocalizedNames() to the lang array
    • Call $this->repository->create(...)
    • Return the new {Domain}Id
  • Catch persistence exceptions, rethrow as domain exceptions

Reference: src/Adapter/Tax/CommandHandler/AddTaxHandler.php (simple), src/Adapter/Manufacturer/CommandHandler/AddManufacturerHandler.php (with image)

2. Edit handler (partial-update)

Edit{Domain}Handler.php implementing Edit{Domain}HandlerInterface:

  • Load entity: $entity = $this->repository->get{Domain}($command->getId())
  • For each field: if ($command->getName() !== null) { $entity->name = $command->getName(); }
  • Apply only non-null fields — never overwrite with null
  • Call $this->repository->update($entity)
  • Sub-resource commands are dispatched independently, not composed here

Reference: src/Adapter/Tax/CommandHandler/EditTaxHandler.php (simple), src/Adapter/Carrier/CommandHandler/EditCarrierHandler.php (many fields)

3. Delete handler

Delete{Domain}Handler.php implementing Delete{Domain}HandlerInterface:

  • Load entity to verify existence (throws {Domain}NotFoundException)
  • Check business constraints: if entity is referenced by active orders/other entities, throw CannotDelete{Domain}Exception
  • Call $this->repository->delete($command->getId())

4. Toggle status handler

Toggle{Domain}StatusHandler.php:

  • Load entity by ID
  • Flip: $entity->active = !$entity->active
  • Call repository update
  • Return void — the controller reads back state from the grid

5. Sub-resource handler (if sub-resources exist)

Set{Domain}{SubResource}sHandler.php:

Two strategies depending on complexity:

Strategy A: Atomic replace (simpler, quicker)

Used when sub-resources have no identity of their own or when maintaining existing rows isn't important:

  • Begin a DB transaction
  • Delete all existing sub-resource rows for the entity
  • Insert new rows from $command->getItems()
  • Commit; on failure, rollback and throw domain exception
  • Empty array = delete all (valid use case)

Reference: src/Adapter/Carrier/CommandHandler/SetCarrierRangesHandler.php

Strategy B: Incremental update (cleaner, preserves existing sub-resources)

Preferred when sub-resources have their own identity or when preserving existing rows matters (e.g., to keep audit trails, auto-increment IDs, or related data):

  • Load existing sub-resources for the entity
  • Compare with the new collection: identify additions, updates, and removals
  • Apply only the necessary changes (insert new, update changed, delete removed)
  • Wrap in a transaction

Choose Strategy B when possible for cleaner data management. Use Strategy A when sub-resources are simple value-like collections without individual identity.

6. Get-for-editing handler

Get{Domain}ForEditingHandler.php in QueryHandler/:

  • Load entity via repository
  • Map ALL fields to the return DTO: scalars, multilingual (array keyed by langId), related IDs
  • Return typed Editable{Domain} DTO (with scalar types only — no VOs in the DTO)
  • No write side effects

Reference: src/Adapter/Tax/QueryHandler/GetTaxForEditingHandler.php (simple)

7. List query handler (if explicit query exists)

Most domains use the grid QueryBuilder pattern — no handler needed. Only create if the domain uses an explicit Get{Domain}sForListing query class.

Rules

Conventions (attributes, no SQL, no cross-handler calls, return types) are in CQRS/CONTEXT.md. Skill-specific reminders:

  • Check null before every field update in Edit handler (partial-update pattern)
  • Always verify existence before deletion — never delete blindly