macpaw / request-dto-resolver
Request DTO resolver bundle
Installs: 8 333
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 17
Forks: 0
Open Issues: 0
Type:symfony-bundle
Requires
- php: >=8.0
- symfony/form: ^6.4|^7.0
- symfony/framework-bundle: ^6.4|^7.0
- symfony/serializer: ^6.4|^7.0
- symfony/validator: ^6.4|^7.0
Requires (Dev)
- escapestudios/symfony2-coding-standard: 3.x-dev
- phpstan/phpstan: ^1.0
- phpunit/phpunit: ^10.0
- slevomat/coding-standard: ^8.0
- squizlabs/php_codesniffer: ^3.0
- symfony/yaml: ^6.4|^7.0
This package is auto-updated.
Last update: 2025-06-26 11:10:16 UTC
README
Automatically resolves and validates Symfony HTTP request data (JSON, form-data, query parameters) into DTOs.
Features
- Automatic resolution of request data into DTOs.
- Seamless support for JSON, form-data, and query string parameters.
- Built-in validation using the Symfony Form component.
- Support for complex nested data structures.
- Customizable parameter resolution order and field mapping.
- Smart integration with other bundles that parse the request body.
Installation
composer require macpaw/request-dto-resolver
The bundle should be automatically registered in your config/bundles.php
. If not, add it manually:
// config/bundles.php return [ RequestDtoResolver\RequestDtoResolverBundle::class => ['all' => true], // ... ];
Configuration
First, define an interface that your DTOs will implement. This allows the resolver to identify which arguments to process.
// src/DTO/RequestDtoInterface.php namespace App\DTO; interface RequestDtoInterface { }
Then, point the bundle to this interface in a configuration file:
# config/packages/request_dto_resolver.yaml request_dto_resolver: target_dto_interface: App\DTO\RequestDtoInterface
How It Works
The resolver uses a combination of a DTO class and a Symfony Form to process and validate incoming request data.
- Controller Argument: You type-hint a controller argument with your DTO class (e.g.,
UserDto
). - FormType Attribute: You decorate the controller action with the
#[FormType]
attribute, specifying which Symfony Form to use for processing. - Data Resolution: The resolver extracts data from the request based on the form's fields.
- Validation: The form validates the data against the constraints defined in your DTO.
- DTO Hydration: If validation passes, a new DTO instance is created and populated with the validated data.
Usage
1. Create a DTO
The DTO is a simple PHP class that implements your marker interface. Use Symfony's Validator components to define constraints.
// src/DTO/UserDto.php namespace App\DTO; use Symfony\Component\Validator\Constraints as Assert; class UserDto implements RequestDtoInterface { #[Assert\NotBlank] #[Assert\Length(min: 3)] public string $name; #[Assert\NotBlank] #[Assert\Email] public string $email; /** @var string[] */ #[Assert\Count(min: 1)] #[Assert\All([ new Assert\NotBlank, new Assert\Length(min: 2) ])] public array $tags = []; }
2. Create a Form Type
The Form Type defines the structure of the expected request data and maps it to your DTO.
// src/Form/UserFormType.php namespace App\Form; use App\DTO\UserDto; use Symfony\Component\Form\AbstractType; use Symfony\Component\Form\Extension\Core\Type\CollectionType; use Symfony\Component\Form\Extension\Core\Type\EmailType; use Symfony\Component\Form\Extension\Core\Type\TextType; use Symfony\Component\Form\FormBuilderInterface; use Symfony\Component\OptionsResolver\OptionsResolver; class UserFormType extends AbstractType { public function buildForm(FormBuilderInterface $builder, array $options): void { $builder ->add('name', TextType::class) ->add('email', EmailType::class) ->add('tags', CollectionType::class, [ 'entry_type' => TextType::class, 'allow_add' => true, ]); } public function configureOptions(OptionsResolver $resolver): void { $resolver->setDefaults([ 'data_class' => UserDto::class, ]); } }
3. Use in a Controller
In your controller, type-hint the action argument with your DTO class and add the #[FormType]
attribute.
// src/Controller/UserController.php namespace App\Controller; use App\DTO\UserDto; use App\Form\UserFormType; use RequestDtoResolver\Attribute\FormType; use Symfony\Component\HttpFoundation\JsonResponse; class UserController { #[FormType(UserFormType::class)] public function __invoke(UserDto $dto): JsonResponse { // $dto is now a validated and populated object return new JsonResponse([ 'name' => $dto->name, 'email' => $dto->email, 'tags' => $dto->tags, ]); } }
Parameter Resolution
The resolver automatically extracts data from the request to populate the form. The source of the data depends on the request's Content-Type
header and method.
Resolution Order
For each field defined in your Form Type, the resolver searches for a corresponding value in the following order:
- JSON Body: If the request has a
Content-Type
ofapplication/json
, the decoded JSON body is checked first. - Query & Form Data: The resolver then checks
request->query
(forGET
parameters) andrequest->request
(forPOST
form data). - Request Headers: Finally, it checks the request headers.
This order means that for a POST
request with both a JSON body and query parameters, the values in the JSON body will take precedence.
Common Scenarios
- POST with JSON Body:
{"name": "John"}
->name
is resolved from JSON. - POST with Form Data:
name=John
->name
is resolved from form data. - GET with Query Parameters:
?name=John
->name
is resolved from query string. - GET with
Content-Type: application/json
: The resolver will correctly ignore the header and still pull data from the query string, preventing malformed body errors. - Request without
Content-Type
: The request is treated as a standard form/query request, and data is resolved from the query string.
Advanced Features
Custom Field Mapping
You can map request fields to different DTO properties using the lookupKey
option in your Form Type. This is useful for handling request keys that don't match your DTO property names (e.g., user-id
vs. userId
).
Form Type Configuration:
// ... $builder->add('userId', TextType::class, [ 'attr' => ['lookupKey' => 'user-id'], ]); // ...
This configuration will map the user-id
key from any source (JSON body, query, or header) to the userId
form field.
Request Example:
POST /api/some-endpoint Content-Type: application/json { "user-id": 123 }
Integration with Other Bundles
This bundle is designed to work seamlessly with other bundles that parse the request body (e.g., FOSRestBundle). If the request body is already parsed and populated in $request->request
, the resolver will automatically use this pre-parsed data instead of reading the raw body again.
This ensures:
- No double-parsing of the request body.
- Consistent validation and mapping rules.
- Zero-configuration interoperability.
Error Handling
The bundle throws the following exceptions, which you can handle with a standard Symfony exception listener:
InvalidParamsDtoException
: For validation errors (contains aConstraintViolationList
).BadRequestHttpException
: For a malformed JSON body.UnsupportedMediaTypeHttpException
: For an unsupportedContent-Type
.MissingFormTypeAttributeException
: When the#[FormType]
attribute is missing on the controller action.
Contributing
Feel free to open issues and submit pull requests.
License
This bundle is released under the MIT license.