events.md

The Event System

Warning

In API Platform 4.0 with Symfony, you need use_symfony_listeners: true to activate event listeners.

---

Note

Using Kernel event with API Platform should be mostly limited to tweaking the generated HTTP response. Also, GraphQL is not supported. We recommend to use System providers and processors to extend API Platform internals.

API Platform Core implements the Action-Domain-Responder pattern. This implementation is covered in depth in the Creating custom operations and controllers chapter.

Basically, API Platform Core executes an action class that will return an entity or a collection of entities. Then a series of event listeners are executed which validate the data, persist it in database, serialize it (typically in a JSON-LD document) and create an HTTP response that will be sent to the client.

To do so, API Platform Core leverages events triggered by the Symfony HTTP Kernel. You can also hook your own code to those events. There are handy and powerful extension points available at all points of the request lifecycle.

If you are using Doctrine, lifecycle events (ORM, MongoDB ODM) are also available if you want to hook into the persistence layer's object lifecycle.

Built-in Event Listeners

These built-in event listeners are registered for routes managed by API Platform:

Name	Event	Pre & Post hooks	Priority	Description
AddFormatListener	kernel.request	None	28	Guesses the best response format (content negotiation)
ReadListener	kernel.request	PRE_READ, POST_READ	4	Retrieves data from the persistence system using the state providers (GET, PUT, PATCH, DELETE)
QueryParameterValidateListener	kernel.request	None	2	Validates query parameters
DeserializeListener	kernel.request	PRE_DESERIALIZE, POST_DESERIALIZE	2	Deserializes data into a PHP entity (POST); updates the entity retrieved using the state provider (PUT, PATCH)
DenyAccessListener	kernel.request	None	1	Enforces access control using Security expressions
ValidateListener	kernel.view	PRE_VALIDATE, POST_VALIDATE	64	Validates data (POST, PUT, PATCH)
WriteListener	kernel.view	PRE_WRITE, POST_WRITE	32	Persists changes in the persistence system using the state processors (POST, PUT, PATCH, DELETE)
SerializeListener	kernel.view	PRE_SERIALIZE, POST_SERIALIZE	16	Serializes the PHP entity in string according to the request format
RespondListener	kernel.view	PRE_RESPOND, POST_RESPOND	8	Transforms serialized to a Symfony\Component\HttpFoundation\Response instance
AddLinkHeaderListener	kernel.response	None	0	Adds a Link HTTP header pointing to the Hydra documentation
ValidationExceptionListener	kernel.exception	None	0	Serializes validation exceptions in the Hydra format
ExceptionListener	kernel.exception	None	-96	Serializes PHP exceptions in the Hydra format (including the stack trace in debug mode)

Some of these built-in listeners can be enabled/disabled by setting operation attributes:

Attribute	Type	Default	Description
query_parameter_validate	bool	true	Enables or disables QueryParameterValidateListener
read	bool	true	Enables or disables ReadListener
deserialize	bool	true	Enables or disables DeserializeListener
validate	bool	true	Enables or disables ValidateListener
write	bool	true	Enables or disables WriteListener
serialize	bool	true	Enables or disables SerializeListener

Some of these built-in listeners can be enabled/disabled by setting request attributes (for instance in the defaults attribute of an operation):

Attribute	Type	Default	Description
_api_receive	bool	true	Enables or disables ReadListener, DeserializeListener, ValidateListener
_api_respond	bool	true	Enables or disables SerializeListener, RespondListener
_api_persist	bool	true	Enables or disables WriteListener

Custom Event Listeners

Registering your own event listeners to add extra logic is convenient.

The ApiPlatform\Symfony\EventListener\EventPriorities class comes with a convenient set of class constants corresponding to commonly used priorities:

Constant	Event	Priority
PRE_READ	kernel.request	5
POST_READ	kernel.request	3
PRE_DESERIALIZE	kernel.request	3
POST_DESERIALIZE	kernel.request	1
PRE_VALIDATE	kernel.view	65
POST_VALIDATE	kernel.view	63
PRE_WRITE	kernel.view	33
POST_WRITE	kernel.view	31
PRE_SERIALIZE	kernel.view	17
POST_SERIALIZE	kernel.view	15
PRE_RESPOND	kernel.view	9
POST_RESPOND	kernel.response	0

In the following example, we will send a mail each time a new book is created using the API:

<?php
// api/src/EventSubscriber/BookMailSubscriber.php

namespace App\EventSubscriber;

use ApiPlatform\Symfony\EventListener\EventPriorities;
use App\Entity\Book;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Event\ViewEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Mime\Email;
use Symfony\Component\Mailer\MailerInterface;

final class BookMailSubscriber implements EventSubscriberInterface
{
    public function __construct(private MailerInterface $mailer)
    {
    }

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

    public function sendMail(ViewEvent $event): void
    {
        $book = $event->getControllerResult();
        $method = $event->getRequest()->getMethod();

        if (!$book instanceof Book || Request::METHOD_POST !== $method) {
            return;
        }

        $message = (new Email())
            ->from('system@example.com')
            ->to('contact@les-tilleuls.coop')
            ->subject('A new book has been added')
            ->text(sprintf('The book #%d has been added.', $book->getId()));

        $this->mailer->send($message);
    }
}

If you use the official API Platform distribution, creating the previous class is enough. The Symfony DependencyInjection component will automatically register this subscriber as a service and will inject its dependencies thanks to the autowiring feature.

Alternatively, the subscriber must be registered manually.