shrikeh/adr-contracts

Contracts for Action Domain Responder (ADR) projects

dev-main 2024-12-20 12:17 UTC

Requires

• shrikeh/common-app: @dev

Requires (Dev)

• ext-xdebug: *
• google/protobuf: ^4.29
• nyholm/psr7: ^1.8
• phpbench/phpbench: ^1.3
• phpstan/phpdoc-parser: ^1.31
• psr/http-message: ^2.0
• shrikeh/app-symfony: @dev
• shrikeh/php-coding-bible: >=0.2.0
• shrikeh/symfony-api-context: @dev
• shrikeh/teapot: ^3.0
• shrikeh/testing-metapackage: >=0.3
• symfony/console: ^7.2
• symfony/dotenv: *
• symfony/runtime: ^7.2

MIT

• Barney Hanlon

README

This package provides interfaces for Action Domain Responder (ADR) applications. In this instance, the Action can be either an HTTP Action (using the PSR-7 Http Message interface) or a Console Action (which uses the Symfony Console component).

Action

Actions are expected to be:

• A single activity exposed by the application. Unlike HTTP controllers which frequently have many public methods for different RESTful verbs, an Action only ever does one thing. This helps with CQRS, testing, etc.
• A name that is friendly (or, at least, sympathetic to) the language of the user, which can be separate from the language of the domain.

So, a pet store API may have a BuyABunny HTTP action, but it interacts with the domain logic describing purchasing livestock or similarly cold hard truths.

Domain

If ued with the shrikeh/common-app package, the Domain is not directly interacted with, but rather a Message is passed to a Command or Query bus, and a Result returned.

Returning to our pet store, this might mean that a PurchaseLivestock Command is created (complete with details of said bunny), and a Result of LivestockPurchased returned from the bus.

Responder

Following on from above, the role of a Responder is to translate the Result returned from the bus into the corresponding expected output. For example, the HttpResponder interface takes a Result and returns a PSR-7 ResponseInterface. Under the hood, the Responder could use a templating system such as Twig, or a Hypermedia API.

Example

Here is our BuyABunny Action: