Handling Data Transfer Objects (DTOs)

How to Use a DTO for Writing

Sometimes it’s easier to use a DTO than an Entity when performing simple operation. For example, the application should be able to send an email when someone has lost its password.

So let’s create a basic DTO for this request:

<?php
// api/src/Api/Dto/ForgotPasswordRequest.php

namespace App\Api\Dto;

use ApiPlatform\Core\Annotation\ApiResource;
use Symfony\Component\Validator\Constraints as Assert;

/**
 * @ApiResource(
 *      collectionOperations={
 *          "post"={
 *              "path"="/users/forgot-password-request",
 *          },
 *      },
 *      itemOperations={},
 * )
 */
final class ForgotPasswordRequest
{
    /**
     * @Assert\NotBlank
     * @Assert\Email
     */
    public $email;
}

In this case, we disable all operations except POST.

Then, thanks to the event system, it’s possible to intercept the POST request and to handle it.

First, we should define a custom loader paths and create an event subscriber:

define a custom loader paths for Api/Dto:

api_platform:
    mapping:
        paths: ['%kernel.project_dir%/src/Api/Dto']

create an event subscriber:

<?php
// api/src/Api/EventSubscriber/UserSubscriber.php

namespace App\Api\EventSubscriber;

use ApiPlatform\Core\EventListener\EventPriorities;
use App\Entity\User;
use App\Manager\UserManager;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpKernel\Event\GetResponseForControllerResultEvent;
use Symfony\Component\HttpKernel\KernelEvents;

final class UserSubscriber implements EventSubscriberInterface
{
    private $userManager;

    public function __construct(UserManager $userManager)
    {
        $this->userManager = $userManager;
    }

    public static function getSubscribedEvents()
    {
        return [
            KernelEvents::VIEW => ['sendPasswordReset', EventPriorities::POST_VALIDATE],
        ];
    }

    public function sendPasswordReset(GetResponseForControllerResultEvent $event)
    {
        $request = $event->getRequest();

        if ('api_forgot_password_requests_post_collection' !== $request->attributes->get('_route')) {
            return;
        }

        $forgotPasswordRequest = $event->getControllerResult();

        $user = $this->userManager->findOneByEmail($forgotPasswordRequest->email);

        // We do nothing if the user does not exist in the database
        if ($user) {
            $this->userManager->requestPasswordReset($user);
        }

        $event->setResponse(new JsonResponse(null, 204));
    }
}

Then this class should be registered as a service, then tagged.

If service autowiring and autoconfiguration are enabled (it’s the case by default), you are done!

Otherwise, the following configuration is needed:

# api/config/services.yaml
services:
    # ...
    'App\Api\EventSubscriber\UserSubscriber':
        arguments:
            - '@app.manager.user'
        # Uncomment the following line only if you don't use autoconfiguration
        #tags: [ 'kernel.event_subscriber' ]

How to Use a DTO for Reading

Sometimes, you need to retrieve data not related to an entity. For example, the application can send the list of supported locales and the default locale.

So let’s create a basic DTO for this datas:

<?php
// api/src/Dto/LocalesList.php

namespace App\Dto;

final class LocalesList
{
    /**
     * @var array
     */
    public $locales;

    /**
     * @var string
     */
    public $defaultLocale;
}

And create a controller to send them:

<?php
// api/src/Controller/LocaleController.php

namespace App\Controller;

use App\DTO\LocalesList;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Routing\Annotation\Route;

class LocaleController extends AbstractController
{
    /**
     * @Route(
     *     path="/api/locales",
     *     name="api_get_locales",
     *     methods={"GET"},
     *     defaults={
     *          "_api_respond"=true,
     *          "_api_normalization_context"={"api_sub_level"=true}
     *     }
     * )
     */
    public function __invoke(): LocalesDTO
    {
        $response = new LocalesList();
        $response->locales = explode('|', $this->getParameter('app_locales'));
        $response->defaultLocale = $this->getParameter('locale');

        return $response;
    }
}

As you can see, the controller doesn’t return a Response, but the data object directly. Behind the scene, the SerializeListener catch the response, and thanks to the _api_respond flag, it serializes the object correctly.

To deal with arrays, we have to set the api_sub_level context option to true. It prevents API Platform’s normalizers to look for a non-existing class marked as an API resource.

Adding this Custom DTO reading in Swagger Documentation.

By default, ApiPlatform Swagger UI integration will display documentation only for ApiResource operations. In this case, our DTO is not declared as ApiResource, so no documentation will be displayed.

There is two solutions to achieve that:

Use Swagger Decorator

By following the doc about Override the Swagger Documentation and adding the ability to retrieve a _api_swagger_context in route parameters, you should be able to display your custom endpoint.

<?php
// src/App/Swagger/ControllerSwaggerDecorator

namespace App\Swagger;

use Symfony\Component\Routing\RouterInterface;
use Symfony\Component\Serializer\Normalizer\NormalizerInterface;

final class ControllerSwaggerDecorator implements NormalizerInterface
{
    private $decorated;

    private $router;

    public function __construct(
        NormalizerInterface $decorated,
        RouterInterface $router
    ) {
        $this->decorated = $decorated;
        $this->router = $router;
    }

    public function normalize($object, $format = null, array $context = [])
    {
        $docs = $this->decorated->normalize($object, $format, $context);
        $mimeTypes = $object->getMimeTypes();
        foreach ($this->router->getRouteCollection()->all() as $routeName => $route) {
            $swaggerContext = $route->getDefault('_api_swagger_context');
            if (!$swaggerContext) {
                // No swagger_context set, continue
                continue;
            }

            $methods = $route->getMethods();
            $uri = $route->getPath();

            foreach ($methods as $method) {
                // Add available mimesTypes
                $swaggerContext['produces'] ?? $swaggerContext['produces'] = $mimeTypes;

                $docs['paths'][$uri][\strtolower($method)] = $swaggerContext;
            }
        }

        return $docs;
    }

    public function supportsNormalization($data, $format = null)
    {
        return $this->decorated->supportsNormalization($data, $format);
    }
}

#config/services.yaml
# ...
    'App\Swagger\ControllerSwaggerDecorator':
        decorates: 'api_platform.swagger.normalizer.documentation'
        arguments: [ '@App\Swagger\ControllerSwaggerDecorator.inner']
        autoconfigure: false

And finally, complete the Route annotation of your controller like this:

<?php
// api/src/Controller/LocaleController.php

use Nelmio\ApiDocBundle\Annotation\Model;
use Swagger\Annotations as SWG;

//...

    /**
     * @Route(
     *     path="/api/locales",
     *     name="api_get_locales",
     *     methods={"GET"},
     *     defaults={
     *          "_api_respond"=true,
     *          "_api_normalization_context"={"api_sub_level"=true},
     *          "_api_swagger_context"={
     *              "tags"={"Locales"},
     *              "summary"="Retrieve locales availables",
     *              "parameters"={},
     *              "responses"={
     *                  "200"={
     *                      "description"="List of available locales and the default locale",
     *                      "schema"={
     *                          "type"="object",
     *                          "properties"={
     *                              "defaultLocale"={"type"="string"},
     *                          }
     *                      }
     *                  }
     *              }
     *          }
     *     }
     * )
     */
    public function __invoke()

Use NelmioApiDoc

With NelmioApiDoc, you should be able to add annotations to your controllers :

<?php
// api/src/Controller/LocaleController.php

use Nelmio\ApiDocBundle\Annotation\Model;
use Swagger\Annotations as SWG;

//...

    /**
     * @Route(
     *     path="/api/locales",
     *     name="api_get_locales",
     *     methods={"GET"},
     *     defaults={
     *          "_api_respond"=true,
     *          "_api_normalization_context"={"api_sub_level"=true}
     *     }
     * )
     * @SWG\Tag(name="Locales")
     * @SWG\Response(
     *     response=200,
     *     description="List of available locales and the default locale",
     *     @SWG\Schema(ref=@Model(type=LocalesList::class)),
     * )
     */
    public function __invoke()

You can also help us improve the documentation of this page.