Download the PHP package digital-craftsman/cqs-routing without Composer
On this page you can find all versions of the php package digital-craftsman/cqs-routing. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download digital-craftsman/cqs-routing
More information about digital-craftsman/cqs-routing
Files in digital-craftsman/cqs-routing
Package cqs-routing
Short Description Reduced cost of change through CQS in Symfony
License MIT
Informations about the package cqs-routing
Reduced cost of change through CQS in Symfony
Installation and configuration
Install package through composer:
Then add the following cqs-routing.php
file to your config/packages
and replace it with your instances of the interfaces:
You can find the full configuration here (including an example configured with yaml).
The package contains instances for request decoder, DTO constructor and response constructor. With this you can already use it. You only need to create your own DTO validators, request data transformers and handler wrappers when you want to use those.
Where and how to use the instances, is described below.
Why
It's very easy to build a CRUD and REST API with Symfony. There are components like parameter converter which are all geared towards getting data very quickly into a controller to handle the logic there. Unfortunately even though it's very fast to build endpoints with a REST mindset, it's very difficult to handle business logic in a matter that makes changes easy, independent and secure. In short, we have a low cost of introduction at the expense of the cost of change.
Using CQS means fewer dependencies between endpoints and data models and therefore less surface for breaking one endpoint when working on another one. Symfony recently has added more support of constructing DTOs directly in the controller, but there are still a few pieces missing.
The CQS routing bundle closes this gap and drastically reduces the cost of change with only slightly higher costs of introduction.
Overarching goals
The bundle makes it easier to use CQS and has to following goals:
- Make it very fast and easy to understand what is happening (from a business logic perspective).
- Make the code safer through extensive use of value objects.
- Make refactoring safer through the extensive use of types.
- Add clear boundaries between business logic and application / infrastructure logic.
How
The bundle consists of two starting points, the CommandController
and the QueryController
and the following components:
- Request validator (Examples)
Validates request on an application level. - Request decoder (Examples)
Decodes the request and transforms it into request data as an array structure. - Request data transformer (Examples)
Transforms the previously generated request data. - DTO constructor (Examples)
Generates a command or query from the request data. - DTO validator (Examples)
Validates the created command or query. - Handler (Examples)
Command or query handler which contains the business logic. - Handler wrapper (Examples)
Wraps handler to execute logic as a prepare / try / catch logic. - Response constructor (Examples)
Transforms the gathered data of the handler into a response.
The process how the controller handles a request can be and when to use which component is described here.
Routing
Through the Symfony routing, we define which instances of the components (if relevant) are used for which route. We use PHP files for the routes instead of the default YAML for more type safety and so that renaming of components is easier through the IDE.
A route might look like this:
You only need to define the components that differ from the defaults configured in the cqs-routing.php
configuration. Read more about routing here.
Command example
Commands and queries are strongly typed value objects which already validate whatever they can. Here is an example command that is used to create a news article:
The structural validation is therefore already done through the creation of the command and the command handler only has to handle the business logic validation. A command handler might look like this:
Sponsors
All versions of cqs-routing with dependencies
symfony/framework-bundle Version ^6.4|^7.0
symfony/serializer Version ^6.4|^7.0