Download the PHP package visual-craft/rest-base-bundle without Composer

RestBase Bundle

Symfony Bundle which provides base foundation for REST API applications. Features include:

• Exception converter: transforms exceptions and errors to structured responses (JSON, XML).
• (Deprecated since v0.3) Request body deserializer: RESTfull decoding of HTTP request body and Accept headers.
• (Deprecated since v0.3) Failing validator: data validator integrated with Exception converter.
• Possibility to check Api zone using Request attribute.
• Since Symfony 6.3 support: MapRequestPayload, MapQueryString, MapQueryParameter

Installation

Step 1: Install the bundle

$ composer require visual-craft/rest-base-bundle

Step 2: Enable the bundle

If you are not using Flex, you also have to enable the bundle by adding the following line in the app/AppKernel.php:

Serializer

By default, additional attributes that are not mapped to the denormalized object will be ignored by the Serializer component. If you prefer to throw an exception when this happens, set the allow_extra_attributes context option to false:

Errors

Configuration

Using the zone configuration, you can specify zones of application where error converter enabled.

Example:

Supported exceptions

Symfony\Component\Security\Core\Exception\AuthenticationException

All authentication exceptions.

Response body:

Symfony\Component\HttpKernel\Exception\HttpExceptionInterface

HTTP error exceptions.

Response body:

Previous exceptions before HttpException:

• Symfony\Component\Serializer\Exception\UnsupportedFormatException

Response body:

• Symfony\Component\Validator\Exception\ValidationFailedException

Response body:

VisualCraft\RestBaseBundle\Problem\ExceptionToProblemConverters\InsufficientAuthenticationException

Thrown if the user credentials are not sufficiently trusted. This is the case when a user is anonymous and the resource to be displayed has an access role.

Response body:

(Deprecated since v0.3) VisualCraft\RestBaseBundle\Exceptions\InvalidRequestException

Base exception thrown if request body are invalid.

Response body:

(Deprecated since v0.3) VisualCraft\RestBaseBundle\Exceptions\InvalidRequestBodyFormatException

Extends from InvalidRequestException. Thrown when symfony/serializer can't deserialize request body.

Response body:

"cause" field values:

• "unexpected_value" if data fields have invalid values

• "extra_attributes" if request body have extra attributes

  (Deprecated since v0.3) VisualCraft\RestBaseBundle\Exceptions\InvalidRequestContentTypeException

Extends from InvalidRequestException. Thrown when no content type parameter are not pointed or content type have unsupported value.

Response body:

"code" field values:

• "missing" : if content type are not pointed

• "unsupported" : if content have unsupported value

  (Deprecated since v0.3) VisualCraft\RestBaseBundle\Exceptions\ValidationErrorException

Response body:

Symfony\Component\Serializer\Exception\ExtraAttributesException

Response body:

Symfony\Component\Serializer\Exception\UnexpectedValueException

Response body:

Enable support security exceptions

If you use separate firewall for your API, use VisualCraft\RestBaseBundle\Security\AuthenticationEntryPoint

If you want to use your custom entry point class, please edit your class next way:

If Authenticator is used in API, use VisualCraft\RestBaseBundle\Security\AuthenticationFailureHandler for auth error converting

Support custom exception

You can create and add your own exceptions and convertors for them.

• Create your exception

• Create converter (implement VisualCraft\RestBaseBundle\Problem\ExceptionToProblemConverterInterface)

• Register your class as a service and tag it with visual_craft.rest_base.exception_to_problem_converter. If you're using autoconfiguration, Symfony will automatically add this tag.

• Throw exception

• Response body

Request Body Deserializer

Api Body Deserializer contains:

• detect and check deserialization format
• deserialize using symfony/serializer and handle exceptions
• validate using Failing validator

Example:

Content type configuration

Debug

To enable exception stack trace in error response body needed to change config:

Error response example:

Failing Validator

Bundle also provides Failing Validator which validates your data. In case of validation violations it throws exception which are supported by Exception converter, so you will receive structured response when data is not valid:

Tests

Additional Tools

License

This bundle is released under the MIT license. See the complete license in the file: LICENSE