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:
Api/Dto
:api_platform:
mapping:
paths: ['%kernel.project_dir%/src/Api/Dto']
<?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' ]
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.
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:
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);
}
}
Register it as a service:
#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()
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()
Made with love by
Les-Tilleuls.coop can help you design and develop your APIs and web projects, and train your teams in API Platform, Symfony, Next.js, Kubernetes and a wide range of other technologies.
Learn more