Download the PHP package baptiste-contreras/symfony-request-param-bundle without Composer

symfony-request-param-bundle

Goals

This bundle aims at reproduce the Java Spring's Request Param annotation but in PHP with Symfony.

With this bundle you can use PHP 8.1 native attribute to obtain the given result :

In our example,$registerRequest object will be built with the data in the request and validated.

Installation

DtoRequestParam parameters

Several parameters are available for the DtoRequestParam, and it let you modify the behavior of the DTO injection.

• sourceType
• throwDeserializationException
• validateDto
• validationGroups

sourceType

• string sourceType. Default value SourceType::JSON. This let you indicate the type of the input data.

When you change this value, you must ensure that there is a DtoProviderDriverInterface that can supports that type of sourceType. Otherwise, you will get a NoDtoProviderDriverFoundException

A full description of the packaged sourceType is discussed later in this document.

Example :

throwDeserializationException

• bool throwDeserializationException. Default value true.

If true, any exception during the deserialization phase is not captured and is rethrown. If you turn this parameter to false, exception happening during the deserialization will be captured, logged, and null will be injected instead of the DTO.

Example :

validateDto

• bool validateDto. Default value true.

If true, a validation phase will be executed, using the Symfony's validator. If there is any contraint violation, the bundle will throw a custom exception and handle the error formatting and display (more on that later)

If false, no validation is done and your DTO will be injected in your controller's method right after the deserialization.

To set up your validation constraints you can use the official Symfony's documentation , but here is a glimpse :

``

Example :

validationGroups

• array|string validationGroups. Default value ['Default'].

As this bundle use internally the Symfony's validator, we can specify a validation group to only validate a subset of our constraints. You can learn more on that here.

You can pass a single string, meaning only one validation group or an array of string, if you want to use many.

Here is something important to note, if validateDto is true, you can't give an empty array or string ([] or '') or you will get a EmptyValidationGroupsException.

Example :

Sources available

For the moment only the json source is supported. You can extend the bundle by creating a DtoProviderDriverInterface for your needs. Any object that implements this interface will be used internally without any additional action.

When your custom provider's supports method is called and return true, it will be selected for the deserialization.

Here is an example for an XML provider.

You can play with the tag priority of you custom provider if you want to ensure that it's called first. Here is the documentation about that

request_param.dto-provider-driver is the tag associated with the DtoProviderDriverInterface.

An example if you need to modify the priority of your custom provider

JsonDtoProvider

If you specify SourceType::JSON as the sourceType, the JsonDtoProvider service will be used.

Internally it use the Symfony's serializer

For the moment a very basic configuration of the serializer is used, and it populates your DTOs using setters.

Later it will be possible to change that. (Actually you can change that by configuring the serializer component your way, more reading here)

Error Handling

Presenter

An error presenter is a service responsible to return a response in a predefined format. For example json error format :

If you want to add your own error presenter, which return a custom format you just have to create an object that implements ErrorPresenterDriverInterface.

Like the custom provider above, no further actions are required (i.e. if your custom error presenter's supports method returns true, it will be used !).

You must be aware that the first error handler register which returns true will be use. As for the providers, you can play with the tag priority to put your handler first in the selection chain Here is the documentation about that.

request_param.error-presenter-driver is the tag associated with the ErrorPresenterDriverInterface.

An example if you need to modify the priority of your custom provider

When you create your own presenter, in addition of the supports method, you must implement two important methods :

• presentBadRequest : is called for a validation exception or an HTTP 400 error
• presentTechnicalError : is called in any other case

Here is an example of a custom basic HTML error presenter :

JsonErrorPresenter

By default, the JsonErrorPresenter service will be used to returns a JSON response with the error detailed.

Here is an example of 2 responses :

• Given a bad request, it will produce

• Given any other error, the result will be :

You can easily modify this response format. In fact, this presenter use decorator stacks to create a response array.

Symfony's decorator

Symfony's decorator stack

JsonErrorPresenter::presentBadRequest uses the stack_response_formatter_json_bad_request stack. JsonErrorPresenter::presentTechnicalError uses the stack_response_formatter_json_technical_error stack.

Both stacks above are a sequence of JsonFormatterInterface applied one by one.

Lets look at the stack_response_formatter_json_bad_request definition :

Let's create a new formatter to add a new key, and, lets say, remove the key

We need to add a little more configuration in the services.yaml

And voila

With this decorator approach you can really easily customize the json response

Will produce:

By default, request_param.response.formatter.json.validation is responsible for the errors key and request_param.response.formatter.json.default the others you saw in the above examples.