Download the PHP package check24/apitk-dtomapper-bundle without Composer

apitk-dtomapper-bundle - DTO handling

Overview

This bundle adds versioned DTO support for RESTful API's.

Installation

Install the package via composer:

Usage

Setup

Add this to your services.yaml so the bundle can automatically load and use the mapper services:

Writing Mappers

Create a mapper class in the folder src/DtoMapper (or whichever you configured) which implements the MapperInterface and transforms incoming data into a single DTO:

In your controller replace the @Rest\View() annotation with the corresponding @Dto\View() mentioning the mapper to use:

The bundle now automatically transform whatever you return in the action with the help of the given mapper into an DTO. When you return an array of data in your controller, the mapper will be called on every single element. You don't have to worry about that.

You can throw a UnmappableException if you want to skip some elements of the array.

Also the bundle auto generates a swagger response with code 200 and the corresponding DTO scheme (respectively an array of DTOs), so you don't have to add the redundant @SWG\Response(). For this to work, just take care that your Mapper has a correct return typehint (f.e. public function map($data): FoobarDto) and that your controller action has a return annotation, which states if an array or object is returned (f.e. * @return Foobar[]). You can still overwrite this by your own @SWG\Response() annotation.

Turning arrays into Collections

If you return an array in the controller it will be serialized like this. If you do not want to work with an array or can not work with arrays due to technological constraints (protobuf) you can instruct the bundle to turn arrays into collection-classes instead.

To turn an array returned from a controller into a collection, implement the MapperCollectionInterface additionally to the MapperInterface into your mapper.

Example:

This will cause the bundle to call mapCollection as soon as all items have been mapped via map. You can initialize your collection class within the mapCollection method. The object returned here will replace the controller response's content.

Serialized DTO view

If you wish to return the DTOs in a serialize($dto) manner instead of json, implement the available dto view handler.

When calling the API with the Accept: application/vnd.dto header, you will get the DTO as an unserializable string.

Exceptions will also be serialized. Stack Traces, filenames, line numbers and previous exceptions will be omitted when kernel.debug is set to false (= in productive environments) to avoid leaking potentially sensitive information.

Serialized Protobuf view

If you wish to return serialized Protobuf object.