This component allow you to inject DTO object mapped from the Request to the action.
- Install
- Requirements
- Basic usage
- Nested object
- Mapped strategies
- Create custom mapped strategy
- How to create an custom exception?
- Project example
- Contributing
- Licence
- TODO
You can install this package via composer using this command:
composer require maksi/laravel-request-mapper
The package will automatically register itself.
PHP 7.1 or newer and Laravel 5.5 or newer
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:
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.
- 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 validationmessages
andcustomAttributes
, than you can extendMaksi\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',
];
}
}
- 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.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
];
}
}
By default package has 3 strategies:
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.
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 aRequest
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));
}
}
- 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);
}
}
- Define in
config/laravel-request-mapper.php
exception-class
key
<?php
declare(strict_types = 1);
return [
'exception-class' => \Maksi\LaravelRequestMapper\Validation\ResponseException\DefaultException::class,
];
You can see example of usage part of this package in https://github.com/E-ZSTU/rozklad-rest-api project.
Please see CONTRIBUTING for details.
The MIT License (MIT). Please see License File for more information.
- 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)