imediafrance / ammit
[DDD] Stable framework agnostic Command resolver
Installs: 758
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 5
Forks: 2
Open Issues: 7
Type:project
Requires
- php: >=7.0
- psr/http-message: ^1.0
Requires (Dev)
- atoum/atoum: ~2.8
- atoum/stubs: ~2.5
- sensiolabs/security-checker: ^4.0
This package is not auto-updated.
Last update: 2019-02-20 19:08:24 UTC
README
# AmmitA light, stable and framework agnostic Command resolver library
Currently being Battle Tested (not yet 1.0.0 tagged)
- What the lib does
- How to use it ?
- What the lib does not ?
- Why ?
- How does it work ?
- Pragmatic ?
- Want to contribute ?
- Ammit ?
A Command is a simple well named DTO reflecting user intention.
Consequently it shall be immutable.
- RegisterUserCommand
- DisableUserCommand
- BookCargoCommand
What the lib does ?
- It provides a helper to easily extract scalar data from a PSR-7 HTTP Request (or a CLI input) in order to instantiate an immutable Command.
- It allows to implement clean Commands (no public field).
- It is designed to be a simple UI Validation framework dependency free.
- It is designed to ease segregating UI validation Vs Domain validation concerns
How to use it ?
composer require ammit-php/ammit
Example:
Implement a RegisterUserCommandResolver
which will map a PSR-7 ServerRequestInterface
into a RegisterUserCommand
.
Before creating RegisterUserCommand
it will perform a UI validation.
RegisterUserController.php
$registerUserCommandResolver = new RegisterUserCommandResolver(); try { $command = $registerUserCommandResolver->resolve($request); } catch (AbstractNormalizableCommandResolverException $e) { // Return a JSON error following jsonapi.org's format // @see http://jsonapi.org/examples/#error-objects-basics return JsonResponse::fromJsonString( json_encode( $e->normalize() ), 406 ); } try { $this->userService->registerUser($command); } catch(DomainException $e) { // ... } // ...
RegisterUserCommandResolver.php
/** * Resolve a PSR-7 Request into a RegisterUserCommand (Data Transfer Object) */ class RegisterUserCommandResolver extends AbstractPureCommandResolver { /** * @inheritdoc */ public function resolve(ServerRequestInterface $request): RegisterUserCommand { $commandConstructorValues = $this->resolveRequestAsArray($request); // We are using variadic function here (https://wiki.php.net/rfc/variadics) return new RegisterUserCommand(...$commandConstructorValues); } /** * @inheritDoc */ protected function validateThenMapAttributes(ServerRequestInterface $request): array { // $id = $_GET['id'] $id = $this->queryStringValueValidator->mustBeString( $request, 'id' ); // $firstName = $_POST['firstName'] $firstName = $this->attributeValueValidator->mustBeString( $request, 'firstName' ); // $lastName = $_POST['lastName'] $lastName = $this->attributeValueValidator->mustBeString( $request, 'lastName' ); // $email = $_POST['email'] $email = $this->attributeValueValidator->mustBeString( $request, 'email' ); // Will be injected directly in RegisterUserCommand::__construct(...$args) // as variadic function $commandConstructorValues = [ $id, $firstName, $lastName, $email ]; return $commandConstructorValues; } }
Use it with Symfony: http://symfony.com/doc/current/request/psr7.html
Use it with Laravel: TBA
Public API
Pure extending AbstractPureCommandResolver
Raw | $_GET | $_POST | |
$this->rawValueValidator | $this->queryStringValueValidator | $this->attributeValueValidator | |
Boolean | ->mustBeBoolean(...) | ||
String | ->mustBeString(...) | ||
Integer | ->mustBeInteger(...) | ||
Float | ->mustBeFloat(...) | ||
Array | ->mustBeArray(...) | ||
Date | ->mustBeDate(...) | ||
DateTime | ->mustBeDateTime(...) |
Pragmatic extending AbstractPragmaticCommandResolver
Raw | $_GET | $_POST | |
$this->rawValueValidator | $this->queryStringValueValidator | $this->attributeValueValidator | |
Same | as AbstractPureCommandResolver | ||
UUID | ->mustBeUuid(...) | ||
Length | ->mustHaveLengthBetween(...) | ||
->mustBeEmailAddress(...) | |||
Regex | ->mustBeValidAgainstRegex(...) |
What the lib does not ?
- It is not designed to be a Symfony Form Component replacement.
- It is not designed to create complex validation. It's aim is to validate simple scalar. Yet it still allows "pragmatic" complex UI validation for prototyping/RAD.
- It is not designed to use PHP reflection. It is only meant to use Command constructor.
Why ?
We were using Symfony Form Component to map and validate HTTP Requests to our Commands.
But it was way too complex and hacky. And too tempting to put our Domain validation into FormType. Then to "forget" to put it back into our Domain.
Furthermore we wanted to anticipate Immutable class.
How does it work ?
It is using \Closure
internally in order to be able to catch all \Exception
.
Otherwise it would display only 1 validation issue. And we want to see all validation issues at once like with Forms.
Pragmatic ?
You may have needs to put some Domain validation in your UI. Sometimes we need to do some Rapid Application Development when prototyping. And to take shortcuts knowing we will have to pay back our technical debt in a near future.
With Ammit you would use our AbstractPragmaticCommandhenResolver
(Pragmatic) instead of our AbstractPureCommandResolver
(Pure) helper.
It will allow you to use more complex validation like uuid
validation for example:
$email = $attributeValueValidator->mustBeUuid( $request, 'id' );
A validation is missing. You can still inject your own.
Want to contribute ?
Read UBIQUITOUS_LANGUAGE_DICTIONARY.md
Init docker container: docker-compose up -d
Composer install: docker-compose run --rm composer install
Use container: docker/bin/php -v
(first do chmod +x docker/bin/php
)
Add Unit Test then: docker/bin/php bin/atoum
Ammit ?
Ammit, an ancient egyptian goddess involved in heart weighting. She was devouring souls of human judged to be not pure enough to continue their voyage towards Osiris and immortality.