README

This component allow you to inject DTO object mapped from the Request to the action.

1. Install
2. Requirements
3. Basic usage
4. Nested object
5. Mapped strategies
6. Create custom mapped strategy
7. How to create an custom exception?
8. Project example
9. Contributing
10. Licence
11. TODO

1. Install

You can install this package via composer using this command:

composer require maksi/laravel-request-mapper

The package will automatically register itself.

2. Requirements

PHP 7.1 or newer and Laravel 5.5 or newer

3. Basic usage

3.1 Create an DTO object

<?php
declare(strict_types = 1);

use Maksi\LaravelRequestMapper\Filling\RequestData\AllRequestData;

final class RoomSearchRequestData extends AllRequestData
{
    private $name;
 
    protected function init(array $data): void
    {
        $this->name = $data['name'] ?? null;
    }

    public function getName(): string
    {
        return $this->name;
    }
}

Your DTO object should extend one of RequestData classes:

• AllRequestData
• HeaderRequestData
• JsonRequestData

RequestData classes responsible for mapped strategies.

$data array in the init it is an array which return from the mapped strategies classes. Basically $data it is some data from the Request.

3.2 Inject to the action

DTO object can be injected to any type of action.

<?php
declare(strict_types = 1);

/**
 * @package App\Http\Controller
 */
class RoomSearchController
{
 ...
    public function __invoke(RoomSearchRequestData $payload) // DTO object injected
    {
        
    }
}

3.3 Validate DTO object

You can apply validation to the DTO object:

• before mapping data to the DTO (laravel validation)
• after mapping data to the DTO (symfony annotation validation)

3.3.1 Apply laravel validation

Laravel validation applied for the RequestData object before object filling.

1. You should create a class with validation rules. This class should implement Maksi\LaravelRequestMapper\Validation\BeforeType\Laravel\ValidationRuleInterface interface (in case, if you do no need change the validation messages and customAttributes, than you can extend Maksi\LaravelRequestMapper\Validation\BeforeType\Laravel\AbstractValidationRule class)

<?php
declare(strict_types = 1);

namespace Maksi\LaravelRequestMapper\Tests\Integration\LaravelNestedValidation\Stub;

use Maksi\LaravelRequestMapper\Validation\BeforeType\Laravel\AbstractValidationRule;

class ValidatorRule extends AbstractValidationRule
{
    public function rules(): array
    {
        return [
            'nested' => 'array|required',
            'title' => 'string|required',
        ];
    }
}

1. In the next you should apply this rules to the DTO object. This should be done via annotation.

<?php
declare(strict_types = 1);

namespace Maksi\LaravelRequestMapper\Tests\Integration\LaravelNestedValidation\Stub;

use Maksi\LaravelRequestMapper\Filling\RequestData\JsonRequestData;
use Maksi\LaravelRequestMapper\Validation\BeforeType\Laravel\Annotation\ValidationClass;

/**
 * @ValidationClass(class="\Maksi\LaravelRequestMapper\Tests\Integration\LaravelNestedValidation\Stub\ValidatorRule")
 */
class RootRequestDataStub extends JsonRequestData
{
    private $title;

    private $nested;

    protected function init(array $data): void
    {
        $this->title = $data['title'] ?? null;
        $this->nested = new NestedRequestDataStub($data['nested'] ?? []);
    }

    public function getTitle(): string
    {
        return $this->title;
    }

    public function getNested(): NestedRequestDataStub
    {
        return $this->nested;
    }
}

string

@ValidationClass(class="\Maksi\LaravelRequestMapper\Tests\Integration\LaravelNestedValidation\Stub\ValidatorRule")

indicates that before filling current DTO should be appied \Maksi\LaravelRequestMapper\Tests\Integration\LaravelNestedValidation\Stub\ValidatorRule rules for the data which will be injected to the dto.

3.3.2 Apply symfony annotation validation

Annotation symfony validation applied to the properties in the RequestData object (So this validation appied after the creating and DTO object).

At the first you should add the @Type(type="annotation") annotation to the RequestData object. After this you can apply the validation to the DTO object (for more information please see symfony validation documentation)

<?php
declare(strict_types = 1);

namespace Maksi\LaravelRequestMapper\Tests\Integration\AnnotationValidation\Stub;

use Maksi\LaravelRequestMapper\Filling\RequestData\AllRequestData;
use Maksi\LaravelRequestMapper\Validation\Annotation\Type;
use Symfony\Component\Validator\Constraints as Assert;

/**
 * @Type(type="annotation")
 */
class AllRequestDataStub extends AllRequestData
{
    /**
     * @Assert\Type(type="int")
     * @Assert\NotBlank()
     */
    private $allAge;

    /**
     * @var string
     * @Assert\NotBlank()
     */
    private $allTitle;

    protected function init(array $data): void
    {
        $this->allAge = $data['age'] ?? null;
        $this->allTitle = $data['title'] ?? null;
    }

    public function getAllTitle(): string
    {
        return $this->allTitle;
    }

    public function getAllAge(): int
    {
        return $this->allAge;
    }
}

4. Nested object validation

4.1. Symfony annotation validation

In the same way you can create an nested DTO object, for example:

Root class

<?php
declare(strict_types = 1);

namespace Maksi\LaravelRequestMapper\Tests\Integration\AnnotationNestedValidation\Stub;

use Maksi\LaravelRequestMapper\Filling\RequestData\JsonRequestData;
use Maksi\LaravelRequestMapper\Validation\Annotation\Type;
use Symfony\Component\Validator\Constraints as Assert;

/**
 * @Type(type="annotation")
 */
class RootRequestDataStub extends JsonRequestData
{
    /**
     * @Assert\NotBlank()
     * @Assert\Type(type="string")
     */
    private $title;

    /**
     * @Assert\Valid()
     */
    private $nested; // this property should have `Valid` annotation for validate nested object

    protected function init(array $data): void
    {
        $this->title = $data['title'] ?? null;
        $this->nested = new NestedRequestDataStub($data['nested'] ?? []);
    }

    public function getTitle(): string
    {
        return $this->title;
    }

    public function getNested(): NestedRequestDataStub
    {
        return $this->nested;
    }
}

Nested class

<?php
declare(strict_types = 1);

namespace Maksi\LaravelRequestMapper\Tests\Integration\AnnotationNestedValidation\Stub;

use Maksi\LaravelRequestMapper\Filling\RequestData\JsonRequestData;
use Symfony\Component\Validator\Constraints as Assert;

class NestedRequestDataStub extends JsonRequestData
{
    /**
     * @Assert\NotBlank()
     * @Assert\Type(type="string")
     */
    private $nestedTitle;

    protected function init(array $data): void
    {
        $this->nestedTitle = $data['title'] ?? null;
    }

    public function getTitle(): string
    {
        return $this->nestedTitle;
    }
}

4.2. Laravel validation for nested

So, as a laravel validation applied before filling the RequestData object, than you should just create the same validation class as an for no nested validation.

<?php
use Maksi\LaravelRequestMapper\Validation\BeforeType\Laravel\AbstractValidationRule;

class ValidatorRule extends AbstractValidationRule
{
    /**
     * @return array
     */
    public function rules(): array
    {
        return [
            'nested' => 'array|required',
            'title' => 'string|required',
            'nested.title' => 'string|required', // nested object validation
        ];
    }
}

5. Mapped strategies

By default package has 3 strategies:

• AllStrategy
• HeaderStrategy
• JsonStrategy

AllStrategy - responsible for filling data from the $request->all() array. If you want to use this strategy, than your RequestData object should extend AllRequestData class.

HeaderStrategy - responsible for filling data from the $request->header->all() array. If you want to use this strategy, than your RequestData object should extend HeaderRequestData class.

JsonStrategy - responsible for filling data from the $request->json()->all() array. If you want to use this strategy, than your RequestData object should extend JsonRequestData class.

6. Create custom mapped strategy

You can create a custom mapped strategies for our application.

6.1 Create custom strategy

You strategy should implement StrategyInterface;

<?php
declare(strict_types = 1);

namespace App\Http\RequestDataStrategy;

use App\Http\RequestData\TeacherSearchRequestData;
use Illuminate\Http\Request;
use Maksi\LaravelRequestMapper\Filling\Strategies\StrategyInterface;
use Maksi\LaravelRequestMapper\Filling\RequestData\RequestData;

class TeacherSearchStrategy implements StrategyInterface
{
    public function resolve(Request $request): array
    {
        return $request->all();
    }

    public function support(Request $request, RequestData $object): bool
    {
        return $object instanceof TeacherSearchRequestData
            && $request->routeIs('teacher-search');

    }
}

Method support define is strategy available for resolve object. This method has 2 parameters $request and $object:

• $request as a Request instance
• $object - it is empty DTO instance, witch will be filled

Method resolve will return the array which will be injected to the DTO instance. This method accept $request object.

6.2 Create RequestData class for Strategy

You should extend RequestData in case if you want to create your own strategy

<?php
declare(strict_types = 1);

namespace App\Http\RequestData;

use Maksi\LaravelRequestMapper\Filling\RequestData\RequestData;
use Symfony\Component\Validator\Constraints as Assert;

final class TeacherSearchRequestData extends RequestData
{
    /**
     * @var string
     *
     * @Assert\NotBlank()
     * @Assert\Type(type="string")
     */
    private $name;

    protected function init(array $data): void
    {
        $this->name = $data['name'] ?? null;
    }

    public function getName(): string
    {
        return $this->name;
    }
}

6.3 Register your strategy in the ServiceProvider

You should add instance of your strategy to the Maksi\LaravelRequestMapper\StrategiesHandler via addStrategy method.

<?php
declare(strict_types = 1);

namespace App\Http\Provider;

use App\Http\RequestDataStrategy\TeacherSearchStrategy;
use Illuminate\Support\ServiceProvider;
use Maksi\LaravelRequestMapper\FillingChainProcessor;

/**
 * Class RequestMapperProvider
 *
 * @package App\Http\Provider
 */
class RequestMapperProvider extends ServiceProvider
{
    /**
     * @param FillingChainProcessor $fillingChainProcessor
     */
    public function boot(FillingChainProcessor $fillingChainProcessor): void
    {
        $fillingChainProcessor->addStrategy($this->app->make(TeacherSearchStrategy::class));
    }
}

7. Change validation exception

1. Create Exception which will extend \Maksi\LaravelRequestMapper\Validation\ResponseException\AbstractException and implement toResponse method

For example:

<?php

class StringException extends \Maksi\LaravelRequestMapper\Validation\ResponseException\AbstractException
                                implements \Illuminate\Contracts\Support\Responsable
{
    /**
     * Create an HTTP response that represents the object.
     *
     * @param  \Illuminate\Http\Request $request
     *
     * @return \Illuminate\Http\JsonResponse
     */
    public function toResponse($request)
    {
        return \Illuminate\Http\JsonResponse::create('Invalid data provided')
                            ->setStatusCode(\Illuminate\Http\Response::HTTP_UNPROCESSABLE_ENTITY);
    }
}

1. Define in config/laravel-request-mapper.php exception-class key

<?php
declare(strict_types = 1);

return [
    'exception-class' => \Maksi\LaravelRequestMapper\Validation\ResponseException\DefaultException::class,
];

8. Project example

You can see example of usage part of this package in https://github.com/E-ZSTU/rozklad-rest-api project.

Contributing

Please see CONTRIBUTING for details.

License

The MIT License (MIT). Please see License File for more information.

TODO

• think about https://www.reddit.com/r/laravel/comments/af843q/laravel_request_mapper/edx39cj
• think about https://www.reddit.com/r/laravel/comments/af843q/laravel_request_mapper/edx8mci
• delete symfony validation, since I`m not sure that is needed for the laravel community
• add integration tests for change exception
• add priority to the strategies
• how you can get this DTO from the middleware (just register RequestData as a singleton)