README

# Ammit

A 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(...)
Email	->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.

imediafrance / ammit

Maintainers

Details