The missing validation middleware

Welcome to my presentation, I'm glad to be there in person.
I'll start with a quick introduction of myself.
Then, we are going to talk about middlewares, what they are and how they can be useful in your code.
We'll continue with data validation. To keep my talk consistent I'll take a small example which will be used in every step.
I'll try to explain how validation can be done inside your code in different ways and I'll show some limitations that I found in those solutions.
We'll finally discover Valinor, a PHP library that can help you ensure data validation and object consistency inside your code. We'll talk about immutability and object internal state. I'll try to show you how it can help writing cleaner code in your projects.
I know all these subjects are very technical, if you have questions we'll have some time at the end of the talk. I'll be there so don't be shy and reach me after if you want to discuss.
I also prepared a small repository on GitHub, I'll share you the code at the end. All the examples I'll share with you will be there. Also the slides are already online, I'll share the link on Twitter just after.

Stéphane Hulard

CTO ( CH Studio), Trainer, Contributor.

So I'm Stephane Hulard.
▶ I lead a small French company named CH Studio. We are specialized in PHP software development and help our customers build state of the art web application. I also love working on legacy projects to help the teams take them back.
Today we are working on a medical image aggregation and search tool. We are not developing website, and are focused on specific web application.
This explain the main reason we asked us how to improve our input handling and validation methods.

▶ I'm also a trainer, mainly around the software quality tools and methods.
▶ Finally, I'm a contributor. I try to work on Open Source, read a lot of community content and attend conferences. Those different actions help me having a real life vision regarding my work and my daily routine.

Middleware ?

Like an onion 🧅

If you try to represent your application like an onion, you get something like this.
In a web context, everything starts with a Request. This Request is composed of different parts that can be analyzed by your code to return a Response.
If you take a step back for every program even outside the web, you can have the same logic. There is always an input, our program, then an output.
I shown here four layers, we'll go deeper in the input validation after. We can have a lot of different layers.

Different layers…

IN: Request, Preparation, Consolidation

CORE: Execution

OUT: Filtering, Adaptation, Response

For me, a program logic can be splitted in three parts.
▶ The first one is for the input. We got a raw input, we can manipulate and validate it until it reaches the application code at the heart of our onion. In this part, we are also booting the application, loading the PHP code and everything that is mandatory to handle the request.
▶ After that we arrive in the internal application code, also known as the Controller. Its job is to make something interesting with the request. This is where your specific logic is executed so it's important to limit the boilerplate code.
▶ Finally, we can add some logic around the Controller's response, this is where we build the output. For example we can enforce some HTTP headers, convert to a specific format… This is also in this part that the Framework kernel lifecycle will be ended.

…to reuse logic easily !

PSR-15, or specific implementations…

How ?

                            namespace App\Infrastructure\Http\Middlewares;

class Authenticate implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        try {
            $payload = $request->getContent();
            /** Execute here validation logic and extract object */
        } catch (ValidationError $error) {
            return Response::fromValidationError(422, $error);
        }

        return $handler->handle($request);
    }
}

                            namespace App\Infrastructure\Http\Middlewares;

class Authenticate implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        try {
            $payload = $request->getContent();
            /** Execute here validation logic and extract object */
        } catch (ValidationError $error) {
            return Response::fromValidationError(422, $error);
        }

        return $handler->handle($request);
    }
}

                            namespace App\Infrastructure\Http\Middlewares;

class Authenticate implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        try {
            $payload = $request->getContent();
            /** Execute here validation logic and extract object */
        } catch (ValidationError $error) {
            return Response::fromValidationError(422, $error);
        }

        return $handler->handle($request);
    }
}

                            namespace App\Infrastructure\Http\Middlewares;

class Authenticate implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        try {
            $payload = $request->getContent();
            /** Execute here validation logic and extract object */
        } catch (ValidationError $error) {
            return Response::fromValidationError(422, $error);
        }

        return $handler->handle($request);
    }
}

                            namespace App\Infrastructure\Http\Middlewares;

class Authenticate implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        try {
            $payload = $request->getContent();
            /** Execute here validation logic and extract object */
        } catch (ValidationError $error) {
            return Response::fromValidationError(422, $error);
        }

        return $handler->handle($request);
    }
}

The PSR-15 use the Chain of Responsibility pattern. It's designed in a way that we can combine every object in a specific order to obtain a result.
Here is a sample code about a validation middleware. I've simplified it a bit to allow the code to fit in a slide but the important part are there.
▶ You can see that our class extends MiddlewareInterface.
▶ It enforces us to implement the process method which takes the Request and the next handler to be applied.
▶ Our goal here is to generate a response, if the validation part fails, I can stop the process here and return a 422 response.
▶ If you are not familiar with Middlewares it might not be easy to understand. However if we look at the onion picture we can see that we have the input part. Here we are validating the request content. Then we give the request to the next layer. If I want to work on the output, I can retrieve the response from the next layer in a variable and execute some logic on it.
The Chain of Responsibility pattern allow us to build the different layers of our onion.
I show you this code because I find it easier to understand but in your framework of choice it can be different and use Events for example.

Advantages ?

Validate everything before reaching application code …

… Combine and reuse objects easily …

… Centralize logic for easier maintenance.

Validation ?_{Why and How ?}

Now that we are familiar with the concept of Middleware, we can come back to the validation. In most of the web application I worked with, I found that the input validation is bloated inside the controller.
This forces to duplicate validation code when we manipulate the same data in multiple places.
If you work on a small project it might not be a problem but when the codebase will grow, having every piece of logic contained in an object and reused when we need it help a lot. Easier to understand, easier to evolve, you'll thank your future you to have though this way.
The input validation process for me is a part of those contained object. We wait for something, most of the time a highly structured input, then we manipulate it and we come back with a result. If I can express every possible input in an object, I can delegate all the validation logic to ensure that when I read my Controller, everything is ready to use.
No more isset, no more array_key_exists or other structure controls. You create an object with a valid signature, expose some methods and you'll use them safely. It's safe because if an error is found, you'll never reach the Controller thanks to the Middleware.

Start with a problem…

A Contract management project:

▶ As a User I want to create a Contract.
▶ A Contract is composed of dates and an Author.
▶ An Author is identified by its Email address.

                            POST /contracts

{
    "starts_at": "2022-01-01 00:00:00",
    "expires_at": "2022-12-31 00:00:00",
    "author": {
        "name": "Neslon Mandela",
        "email": "nelson.mandela@mail.com"
    }
}

As software developers our goal is to solve problems. For this we write code but we need to understand clearly the problem to find a correct solution.
Here I express a small user story from a contract management project. I want to be able to create a contract so I wrote the expectations. We can see 3 main concepts that can be extracted: Contract, Author, Email.
▶ We can materialize this requirement by adding a new API endpoint in our project which will take the given JSON payload as input.
We now have an input and you can see that it's well defined. We can represent those fields inside some objects that will ensure a consistent state. If we are able to build the object, the data is valid, if not, we might send some errors back to the user.

Define objects: Contract

                            class Contract
{
    public function __construct(
        private DateTimeInterface $startsAt,
        private DateTimeInterface $expiresAt,
        private Author $author
    ) {
        if ($expiresAt < $startsAt) {
            throw new InvalidArgumentException(
                '"expiresAt" date must be after "startsAt".'
            );
        }
    }
}

✅️: "expiresAt" must be after "startsAt"

Define objects: Author

                            class Author
{
    public function __construct(
        private string $name,
        private Email $email
    ) {
        if (empty($name)) {
            throw new InvalidArgumentException(
                "Author name can't be empty."
            );
        }
    }
}

✅️: "name" must not be empty.

Define objects: Email

                            class Email
{
    public function __construct(
        private string $email
    ) {
        if (false === filter_var($email, FILTER_VALIDATE_EMAIL)) {
            throw new \InvalidArgumentException(
                "Email $email is not valid."
            );
        }
    }
}

✅️: "email" must be compliant to RFC.

Object hierarchy

                            {
    "starts_at": "2022-01-01 00:00:00",
    "expires_at": "2022-12-31 00:00:00",
    "author": {
        "name": "Neslon Mandela",
        "email": "nelson.mandela@mail.com"
    }
}

                            {
    "starts_at": "2022-01-01 00:00:00",
    "expires_at": "2022-12-31 00:00:00",
    "author": {
        "name": "Neslon Mandela",
        "email": "nelson.mandela@mail.com"
    }
}

                            {
    "starts_at": "2022-01-01 00:00:00",
    "expires_at": "2022-12-31 00:00:00",
    "author": {
        "name": "Neslon Mandela",
        "email": "nelson.mandela@mail.com"
    }
}

                            {
    "starts_at": "2022-01-01 00:00:00",
    "expires_at": "2022-12-31 00:00:00",
    "author": {
        "name": "Neslon Mandela",
        "email": "nelson.mandela@mail.com"
    }
}

3 objects to express our input: "Contract", "Author", "Email"

Back to basics

                            /**
 * @param DateTimeInterface $startsAt
 * @param DateTimeInterface $expiresAt
 * @param string $authorName
 * @param string $authorEmail
 */
function createContract(
    $startsAt,
    $expiresAt,
    $authorName,
    $authorEmail
) {
    /** code logic */
}

Break it easily…

                            createContract(
    'a',
    'a',
    -18,
    0
);

// Error in the function body because parameters have the wrong type.

With static type hinting !

                            function createContract(
    DateTimeInterface $startsAt,
    DateTimeInterface $expiresAt,
    string $authorName,
    string $authorEmail
) {
    /** code logic */
}

                            createContract(
    'a',
    'a',
    -18,
    0
);

// Type error: Argument 1 passed to createContract() must be DateTimeInterface, string given,
// called in xxx.php on line xx

Now, PHP will help us validating the data. You can see that the function signature was updated. I applied the typing on a function here because it's simple for my slides but you can apply this to you class methods and propreties.
▶ If you try to give a string instead of a DateTimeInterface instance, you'll get a TypeError.
Now we have a code that validates itself that's pretty nice.
But that's not what we want, we don't want to have unhandled PHP TypeError thrown from everywhere. We need to capture the errors. Also here we are just validating that the parameter types are correct.
Most of the time we want to move further with more specific validation rules to ensure consistency. Here I want to be sure that the email string is correctly formed to be an email, I also want the expiresAt date to be after the startsAt.

Only basic PHP typing…

Nice but don't cover all the cases.

Use the objects !

                            function createContract(
    Contract $contract
) {
    /**
     * $contract contains all properties
     * All values are valid and respect the rules.
     */
}

Prepare input data

                            use Symfony\Component\Validator\Constraints as Assert;

class Author
{
    /** @Assert\NotEmpty */
    private string $name;

    public function __construct(
        string $name,
        private Email $email
    ) {
        $this->name = $name;
    }
}

This is still a simple example. I need to update my object definition here if I want to be able to validate it. To use the Symfony validator I choose to write annotations here.
These annotations are powerful because you can combine them and create very complex rules to validate your data.
It's the way this validator works, you initialize a bunch of data then you validate and retrieve the errors based on the rules.
Here I have only one rule, my name must not be empty. I don't need to validate the email because it must have been initialized correctly before, I can trust the Email object. I just show you the Author object as an example, if I want to use the Symfony Validator on my 3 defined objects, I need to change them the same way.

Prepare input data

                            use Symfony\Component\Validator\Validator\ValidatorInterface;

$validator = /** Some code to retrieve the ValidatorInterface instance */
$email = new Email(…);

$author = new Author('', $email);

$errors = $validator->validate($author);
if (count($errors) > 0) {
    //Build error response
}

//Build valid response

                            use Symfony\Component\Validator\Validator\ValidatorInterface;

$validator = /** Some code to retrieve the ValidatorInterface instance */
$email = new Email(…);

$author = new Author('', $email);

$errors = $validator->validate($author);
if (count($errors) > 0) {
    //Build error response
}

//Build valid response

Now we must use a Validator instance to validate our date. It will give us an error list if there are some violations. That's interesting because we don't want to break our code completely on each encontered error. If we can retrieve the whole list, we can explain to the user what's wrong.
▶ My main concern with this approach is that our Author object is build before the validation.
Therefore we are allowing an object like this to be built with an invalid internal state, in our case an empty name. For me that's a huge issue because if sometimes we forget to run the validator, we can't rely on our object anymore. We are getting back the a previous step.

Validates before…

                            $validator = Validator::make($request->all(), [
    'name' => 'required|max:255'
]);

if ($validator->fails()) {
    /** Build error response */
}

$author = new Author($request->get('name'), $email);

                            $validator = Validator::make($request->all(), [
    'name' => 'required|max:255'
]);

if ($validator->fails()) {
    /** Build error response */
}

$author = new Author($request->get('name'), $email);

                            $validator = Validator::make($request->all(), [
    'name' => 'required|max:255'
]);

if ($validator->fails()) {
    /** Build error response */
}

$author = new Author($request->get('name'), $email);

For sure we can validate the data before initializing our object. This other example uses the Laravel validator.
▶ It can take an array as input and a list of validation rules.
▶ The same way than with our previous examples, we can verify if the validation failed or not and we can build our Author object with the validated data.
That's interesting because here we don't need to update our Author object definition. The validation process completely external. However we need to define the rules in two places, first in the Author constructor, then in the Validator call.
Also and it's the same with Symfony, you still need to create your object yourself. You can use a Serializer or create them manually, it's an extra step in your code.

Limitations ?

An input can be very complex…

Modeling as object clearly define expectations…

Validators doesn't work efficiently with those objects.

💡 `cuyz/valinor`

Map any input into a strongly-typed value object structure.

Let's introduce Valinor, a library which allows to take an unstructured input and build a valid object structure from it.
For me it's the best of both worlds, you can define your objects with specific rules then map them to an input. It combines the two approaches I show you before.
Diclaimer, my goal is not to tell that some tools are good and others are bad and should not be used. I just show you another way to validate your data inside your application. I prefer working with objects and Valinor allows me to have validated objects.
The object signatures allow to control everything and it's awesome ! Also if you use Middlewares, it'll help having a central place in your code for your input validation.

How it works ?

Read functions and objects signatures,

Build validation rules by itself,

Validates the data before creating objects,

Ensure that you get ready to use objects at the end.

Show me the code !

                            try {
    $contract = (new \CuyZ\Valinor\MapperBuilder())
        ->mapper()
        ->map(
            Contract::class,
            new \CuyZ\Valinor\Mapper\Source\JsonSource($json)
        );
} catch (\CuyZ\Valinor\Mapper\MappingError $error) {
    // Do something…
}

                            try {
    $contract = (new \CuyZ\Valinor\MapperBuilder())
        ->mapper()
        ->map(
            Contract::class,
            new \CuyZ\Valinor\Mapper\Source\JsonSource($json)
        );
} catch (\CuyZ\Valinor\Mapper\MappingError $error) {
    // Do something…
}

                            try {
    $contract = (new \CuyZ\Valinor\MapperBuilder())
        ->mapper()
        ->map(
            Contract::class,
            new \CuyZ\Valinor\Mapper\Source\JsonSource($json)
        );
} catch (\CuyZ\Valinor\Mapper\MappingError $error) {
    // Do something…
}

                            try {
    $contract = (new \CuyZ\Valinor\MapperBuilder())
        ->mapper()
        ->map(
            Contract::class,
            new \CuyZ\Valinor\Mapper\Source\JsonSource($json)
        );
} catch (\CuyZ\Valinor\Mapper\MappingError $error) {
    // Do something…
}

▶ The code is a bit more complex here because we use a try / catch to retrieve validation errors.
▶ Also the MapperBuilder allows to retrieve the correct object to build your data from the input. It also allows configuring Valinor. There are a lot of documented possibilies.
▶ Once your have written it, it's like some default code. The important part is the map method call which define input data and output object.
With this we can retrieve a complete and valid Contract object. For sure with this example it's a huge solution for a small problem. You might chose a basic and simple tool if you have only one object with a small hierarchy.
However, Valinor allows to map any input to an object and validates it. Think about all the possibilies inside your API payloads or parameters. Also it'll will shine inside a validation Middleware.

Validation errors ?

{
    "starts_at": "2022-01-01 00:00:00",
    "author": {
        "name": "",
        "email": "nelson.mandelamail.com"
    }
}

{
    "expiresAt.value": "Cannot be empty and must be filled with a value matching type.",
    "author.email": "Email nelson.mandelamail.com is not valid.",
    "author": "Author name can't be empty."
}

Supports type annotations

                            class Author
{
    /** @var non-empty-string */
    private string $name;

    public function __construct(
        string $name,
        private Email $email
    ) {
        $this->name = $name;
        if (empty($name)) {
            throw new InvalidArgumentException(
                "Author name can't be empty."
            );
        }
    }
}

                            class Author
{
    /** @var non-empty-string */
    private string $name;

    public function __construct(
        string $name,
        private Email $email
    ) {
        if (empty($name)) {
            throw new InvalidArgumentException(
                "Author name can't be empty."
            );
        }
        $this->name = $name;
    }
}

As we already seen, we can't only rely on PHP typing to define our objects. We need to add other details, a common way is to use annotations. As you can see here, I added the "non-empty-string" annotation to my author object. Since annotation are not real code, I keep my constructor as strict as possible.
To prevent conflicts or duplication of the type annotations, this library tries to handle most of the type annotations that are accepted by PHPStan and Psalm.
▶ If your code is already passed through one of those static analysis tool, nothing to do metadata will be used.
If not, I encourage you to take a look at them, they allow to detect a lot of issues inside your code and you can fix them before it reaches the production server.

Ready to use Objects

                            $contract->author()->email() // Email object

🤯️ ultime validation !

A bit more complex……huge possibilities

Can be extended and adapted to your specific needs

Try Valinor inside a Middleware !

What to do now ?

Give it a try !

A GitHub project with an exhaustive README,

Under active development.

Think about validation

Have you invalid object in your code ?

Are your current tools the best for you ?

Stay open minded 😉️

All the solutions exists for correct reasons,

Stay informed of new tools and practices,

Try new things, you might be surprised !

@s_hulard

https://github.com/CuyZ/Valinor
https://github.com/shulard/ipc-valinor-sample

The missing validation middleware

Stéphane Hulard

Middleware ?

Like an onion 🧅

Different layers…

…to reuse logic easily !

How ?

Advantages ?

Validation ?Why and How ?

Start with a problem…

Define objects: Contract

Define objects: Author

Define objects: Email

Object hierarchy

Back to basics

Break it easily…

With static type hinting !

Only basic PHP typing…

Use the objects !

Prepare input data

Prepare input data

Validates before…

Limitations ?

💡 cuyz/valinor

How it works ?

Show me the code !

Validation errors ?

Supports type annotations

Ready to use Objects

🤯️ ultime validation !

What to do now ?

Give it a try !

Think about validation

Stay open minded 😉️

Validation ?_{Why and How ?}

💡 `cuyz/valinor`