Delivery

The Delivery folder is for any output mechanisms that will produce a response from the system. Here is where any API or web controllers live, console commands, etc. ViewModels would live in this part of the system.

Each major output type should be kept segregated in its own namespace to avoid polluting e.g. the web responses with API responses.

By default Api and Console are provided and are mapped as services already in the services.yaml file.

The API is intended to be fully versioned right from the get go - to ensure backwards compatibility. This versioning should be done at the controller, form and transformer level. Each version should have its own controllers, form requests and transformers. If a particular version does not change one output, you could re-use a previous version if needs be.

FormRequests are a concept from Laravel where you can type hint a validated request object that will ensure that the request contains the data defined in the rules. It provides a somewhat cleaner setup to the Symfony Form library, that can be rather complex to deal with. Using this library is entirely optional. See Form Request Bundle for more details.

For controllers it is best to group then around an aggregate root e.g. there is a User aggregate, so there would be a Users folder in the src/Delivery/Api/V1 folder. Within this folder you could arrange it with folders for Forms and Transformers or include specific ViewModels too.

For the controllers it is best to follow a single controller per action approach e.g.: instead of one controller that contains methods for create, update, destroy, view, list; these are instead separate controllers: CreateController, ListController, ViewController etc. It is up to you how you name these. They could instead by named: DisplayUserAsJson instead of ViewController etc. Whatever naming strategy is used, it should be used consistently.

To help with handling some of the typical request/response cycle of a controller a helper library (somnambulist/api-bundle) is included. This integrates Fractal response transformer through a system similar to DingoAPI. When used in conjunction with the command and query buses, this allows for very thin and light-weight controllers; keeping most of the business logic within the command and query handlers.

View Models a.k.a Presenters

For querying the system e.g. for an API response, create a ViewModel instead of using the main domain models. This allows for customised represents to be used including presentation logic, without filling the domain models with presentation logic. A package: somnambulist/read-models is included to provide this functionality via an active-record approach, however pure SQL / PDO could be used instead.

See the read-models documentation for more details of working with the library.