Dejan Angelov

Testing delayed Symfony Messenger message handling with Behat

Tue, 22 Jul 2025 19:56:00 +0200

Lately, I’ve been working on a hobby project that has many scenarios where operations are getting scheduled to be handled asynchronously in the future - sometimes after a few minutes, sometimes after several hours. Since I’m using Behat for the end-to-end tests, I started exploring ways to test these delayed scenarios as well. There are some good libraries for hooking into the Symfony Messenger transports to verify that messages have been dispatched/scheduled, but my goal with Behat is to focus more on the outcome rather than just the scheduling. In this article, we’ll look at how to “travel” through time, process the scheduled jobs, and assert the expected results.

Imagine that we’re working on an application for incident reporting. Every incident should have a priority assigned, which will be automatically escalated unless the incident is resolved, using the following logic:

All incidents are created with a low priority
After an hour, the priority is escalated to medium
After 5 hours, the priority is escalated to high

We can map these requirements in Gherkin scenarios like this:

Feature: Time-based incident priority escalation

    Scenario: Incident has just been created
        When an incident is created
        Then the incident should have a low priority

    Scenario: Incident not resolved for 1 hour
        Given an incident is created
        And an hour has passed
        Then the incident should have a medium priority

    Scenario: Incident not resolved for 5 hours
        Given an incident is created
        And 5 hours have passed
        Then the incident should have a high priority

Note: This is a simplified example for demonstration purposes. The namespaces in the classes will be omitted, but you can organize them in your application as needed. For simplicity, we'll be using the Symfony Messenger functionalities directly. If you're interested in abstracting these functionalities, I've written an article on that topic few years ago.

First, let’s define our very basic Incident entity. Besides the properties, it’ll have an escalate() method for updating the priority to the next one. As defined in the requirements, every incident will have a low priority by default.

use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
#[ORM\Table(name: 'incidents')]
class Incident
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private int $id;

    #[ORM\Column]
    private string $title;

    #[ORM\Column(enumType: Priority::class)]
    private Priority $priority = Priority::Low;

    #[ORM\Column]
    private bool $resolved = false;

    // ...

    public function escalate(): void
    {
        // check if already resolved, etc.

        $this->setPriority(
            $this->priority->next()
        );
    }
}

For the list of priorities, we’ll have a Priority enum. The enum will also contain the logic for deciding the next priority.

enum Priority: string
{
    case Low = 'low';
    case Medium = 'medium';
    case High = 'high';

    public function next(): Priority
    {
        return match ($this) {
            self::Low => self::Medium,
            self::Medium => self::High,
            self::High => self::High
        };
    }

    // ...
}

In the application, we’ll have defined two message buses - one for commands and one for the background jobs. The commands will always be handled synchronously by the command bus, so we’ll have a commands transport defined that will use the Messenger’s sync transport. The background jobs will be handled asynchronously by the other message bus, so we’ll use a transport that supports delayed handling, e.g. Redis.

framework:
    messenger:
        transports:
            background_jobs:
                dsn: '%env(MESSENGER_TRANSPORT_DSN_BACKGROUND_JOBS)%'
            commands: 'sync://'

        buses:
            background_jobs.bus: ~
            command.bus: ~

# ...

Next, let’s go through the list of steps used in the scenarios above, and write the Behat definitions for each of them.

We’ll be using the FriendsOfBehat/SymfonyExtension Behat extension, which is the officially recommended replacement of the legacy (and now abandoned) Behat/Symfony2Extension extension. This extension will automatically register our contexts as services, as well as autowire and autoconfigure them, thus making it possible to easily inject any other service into them. Additionally, we’ll use its integration for Mink as a driver here, but the same should work for any other driver.

Creating the incident

For simplicity, our application will create a new incident whenever a GET request is received on the “/incidents” path, so we’ll use the Mink session to open that page.

use Behat\Behat\Context\Context;
use Behat\Mink\Session;
use Behat\Step\When;

final class IncidentsContext implements Context
{
    public function __construct(
        private Session $session,
        // ...
    ) {
    }

    #[When('an incident is created')]
    public function anIncidentIsCreated(): void
    {
        $this->session->visit('/incidents');
    }

    // ...
}

On that path, we’ll have a route defined in the IncidentsController controller. From here, we’ll dispatch a command for creating the incident to the command bus we defined above.

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Routing\Attribute\Route;

final class IncidentsController
{
    #[Route('/incidents', name: 'incidents.store', methods: ['GET'])]
    public function store(MessageBusInterface $commandBus): Response
    {
        $commandBus->dispatch(new CreateIncidentCommand('Example incident'));

        return new Response();
    }
}

We’ll define the command class as a message, and we’ll route it to the commands transport.

use Symfony\Component\Messenger\Attribute\AsMessage;

#[AsMessage('commands')]
final readonly class CreateIncidentCommand
{
    public function __construct(
        public string $title
    ) {
    }
}

In the command handler, we’ll initialize a new Incident object, pass the information from the command object, and store it using a repository.

Finally, we’ll use the message bus for the background jobs to schedule two delayed background jobs for escalating the priority. We could dispatch a domain event using another message (event) bus here instead, and have the background jobs be scheduled in a listener, but again, we’re omitting that for simplicity.

Using the Messenger’s DelayStamp, we’ll schedule the first job for an hour - when the incident’s priority may be escalated to medium, and the second job for five hours - when the priority may be escalated to high.

use Symfony\Component\Messenger\Attribute\AsMessageHandler;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Messenger\Stamp\DelayStamp;

#[AsMessageHandler]
final class CreateIncidentCommandHandler
{
    public function __construct(
        private IncidentsRepositoryInterface $incidents,
        private MessageBusInterface $backgroundJobsBus
    ) {
    }

    public function __invoke(CreateIncidentCommand $command): void
    {
        $incident = new Incident();
        $incident->setTitle($command->title);
        // ...

        $this->incidents->store($incident);

        $this->backgroundJobsBus->dispatch(
            new EscalateIncidentPriority($incident->getId()), [
                new DelayStamp(3600000), // 1 hour
            ]
        );

        $this->backgroundJobsBus->dispatch(
            new EscalateIncidentPriority($incident->getId()), [
                new DelayStamp(18000000), // 5 hours
            ]
        );
    }
}

Same as we did with the command, we’ll mark the background job as message, but we’ll route it to the background_jobs transport instead.

use Symfony\Component\Messenger\Attribute\AsMessage;

#[AsMessage('background_jobs')]
final readonly class EscalateIncidentPriority
{
    public function __construct(
        public int $incidentId
    ) {
    }
}

In its handler, we’ll find the Incident record, and use its escalate method that we defined above, then store it back in the database. In a real application, we’ll probably have more checks here as well (e.g. the escalation method may throw an exception that the incident is already resolved).

use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler]
final class EscalateIncidentPriorityHandler
{
    public function __construct(
        private IncidentsRepositoryInterface $incidents
    ) {
    }

    public function __invoke(EscalateIncidentPriority $job): void
    {
        $incident = $this->incidents->find($job->incidentId);

        $incident->escalate();

        $this->incidents->store($incident);
    }
}

Fast-forwarding the current time

For checking the current time in our tests, we’ll use the Symfony’s Clock component and its Symfony\Component\Clock\ClockInterface interface. The component provides a mock clock in the Symfony\Component\Clock\MockClock class, which we’ll use as implementation in the test environment. To achieve that, we’ll update the interface definition in the config/services_test.yaml file:

services:
# ...

    Symfony\Component\Clock\MockClock: ~
    Symfony\Component\Clock\ClockInterface: '@Symfony\Component\Clock\MockClock'

Now that we’ll be getting the mock clock in our contexts, we’ll use its sleep method to move the current time forward for as many hours (or seconds, minutes, etc.) as we want.

use Behat\Behat\Context\Context;
use Behat\Step\Given;
use Symfony\Component\Clock\ClockInterface;

final class TimeTravelContext implements Context
{
    public function __construct(
        private ClockInterface $clock
    ) {
    }

    #[Given('an hour has passed')]
    #[Given(':hours hours have passed')]
    public function anHourHasPassed(int $hours = 1): void
    {
        $this->clock->sleep($hours * 60 * 60);
    }
}

We’ll be using the same clock object later in another context class to get the current time to make sure only the background jobs for which the scheduled timing has passed are handled. At that point, it will already be set to return the time needed for the current scenario.

Verifying the outcome

To verify that only the expected background jobs have been handled, we’ll simply fetch the incident using the repository, and compare its priority to the one defined as expected in the scenario. As we don’t know the ID of the incident, we’ll fetch the last one from the database.

use Behat\Behat\Context\Context;
use Behat\Step\Then;
use Webmozart\Assert\Assert;

final class IncidentsContext implements Context
{
    public function __construct(
        private IncidentsRepositoryInterface $incidents,
        // ...
    ) {
    }

    #[Then('the incident should have a :priority priority')]
    public function theIncidentShouldHaveALowPriority(string $priority): void
    {
        $incident = $this->incidents->last();

        Assert::same(
            Priority::fromString($priority)->value,
            $incident->getPriority()->value,
            "Expected incident to have %s priority, got %s"
        );
    }

    // ...
}

If we now execute the tests, the second and the third scenarios (where we expected the priority to be escalated) will fail.

Feature: Time-based incident priority escalation

    Scenario: Incident has just been created
        When an incident is created
        Then the incident should have a low priority
    
    Scenario: Incident not resolved for 1 hour
        Given an incident is created
        And an hour has passed
        Then the incident should have a medium priority
            Expected incident to have "medium" priority, got "low" (Webmozart\Assert\InvalidArgumentException)
    
    Scenario: Incident not resolved for 5 hours
        Given an incident is created
        And 5 hours have passed
        Then the incident should have a high priority
            Expected incident to have "high" priority, got "low" (Webmozart\Assert\InvalidArgumentException)

This is an expected outcome, as there isn’t any worker running that will be handling the background jobs, so the priorities of the incidents in the failing scenarios never get updated.

Something similar will happen if we update the transport for the background jobs to use the sync one too. In this case, the jobs will be handled immediately after they’re dispatched, thus immediately updating incidents’ priorities to medium and then to high.

Then the incident should have a low priority
    Expected incident to have "low" priority, got "high" (Webmozart\Assert\InvalidArgumentException)

...

Then the incident should have a medium priority
    Expected incident to have "medium" priority, got "high" (Webmozart\Assert\InvalidArgumentException)

Making the tests pass

As we saw, we are already updating the current time in the tests, so the only missing piece is being in control of which background jobs will get handled. That means that we need to be checking the background jobs sent to the message bus, and handling only the ones for which the scheduled time has passed.

To achieve that, we’ll create a new custom Messenger transport, which we’ll use for the background jobs in the test environment.

For a class to be registered and used as Symfony Messenger transport, it has to implement the \Symfony\Component\Messenger\Transport\TransportInterface interface. If we take a look at that interface, we can see that it’s just a combination of the interfaces for the two main parts of the transport - a sender and a receiver.

interface TransportInterface extends ReceiverInterface, SenderInterface
{
}

For our transport implementation to be clearer, we’ll have separate classes for the sender and the receiver. Then, we’ll combine them in a transport class.

A sender is a class responsible for sending the envelopes to the underlying transport, i.e. temporarily persisting the envelopes in some sort of storage, e.g. database, redis, memory, etc., until they’re received by the receiver and passed to a message bus for handling. It has to implement the \Symfony\Component\Messenger\Transport\Sender\SenderInterface interface.

A receiver is a class that is responsible for providing the envelopes stored by the sender to whoever needs to process them. For example, if we have a separate worker running by the messenger:consume console command, it uses the selected transport’s receiver to poll for messages and then send them to the appropriate message bus. In our case we’ll do the same but instead of having a worker running, we’ll use the receiver manually in our step definitions.

Let’s start by defining both the classes and combining them into a class that will implement the Transport interface. For now, let’s focus on the bigger picture and leave the actual implementations for later.

use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\Transport\Sender\SenderInterface;

final class Sender implements SenderInterface
{
    public function send(Envelope $envelope): Envelope { }
}

use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\Transport\Receiver\ReceiverInterface;

final class Receiver implements ReceiverInterface
{
    public function get(): iterable { }

    public function ack(Envelope $envelope): void { }

    public function reject(Envelope $envelope): void { }
}

use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\Transport\TransportInterface;

final class Transport implements TransportInterface
{
    public function __construct(
        private Sender $sender,
        private Receiver $receiver
    ) {
    }

    public function get(): iterable
    {
        return $this->receiver->get();
    }

    public function ack(Envelope $envelope): void
    {
        $this->receiver->ack($envelope);
    }

    public function reject(Envelope $envelope): void
    {
        $this->receiver->reject($envelope);
    }

    public function send(Envelope $envelope): Envelope
    {
        return $this->sender->send($envelope);
    }
}

Now that we have the new transport, we need to:

In the application, send the background jobs to this transport
In the Behat step definitions, use the transport’s receiver to get the messages and pass them to the message bus

To be able to actually use the transport, we need one more piece - a factory that will be creating instances of it. Here we’ll also define a DSN associated to our transport, which will tell Symfony when to use this factory.

use Symfony\Component\Messenger\Transport\Serialization\SerializerInterface;
use Symfony\Component\Messenger\Transport\TransportFactoryInterface;
use Symfony\Component\Messenger\Transport\TransportInterface;

final class TransportFactory implements TransportFactoryInterface
{
    public function __construct(
        private Sender $sender,
        private Receiver $receiver
    ) {
    }

    public function createTransport(
        #[\SensitiveParameter] string $dsn,
        array $options,
        SerializerInterface $serializer
    ): TransportInterface {
        return new Transport($this->sender, $this->receiver);
    }

    public function supports(#[\SensitiveParameter] string $dsn, array $options): bool
    {
        return $dsn === 'time-sensitive-transport://';
    }
}

Next, in config/packages/test/messenger.yaml, using the DSN we defined in the factory, we’ll update the background_jobs transport to use our custom transport.

framework:
    messenger:
        transports:
            background_jobs: 'time-sensitive-transport://'

With that configuration, whenever in our application a background job instance is dispatched to the background jobs message bus, it will be sent using our transport’s sender.

So, now that we know that the background jobs will be reaching it when dispatched, we need to use the same transport in the Behat step definitions to make sure they’re handled when needed. For that, we’ll create a Behat hook that will be executed before each step in our scenarios. In this hook, we’ll use the transport’s get method (implemented in the receiver) which will give us all the messages that have been previously kept by the sender.

Each of the messages given to us by the transport will be in the form of an Envelope object, and will contain a DispatchAtStamp stamp (which, as we’ll see in a bit, we’ll be adding in the sender). Using these stamps, we’ll check if the scheduled time has already passed. If yes, we’ll provide the message to the background jobs message bus for further handling by the appropriate background job handler. If no exception is thrown during the handling of the message, we’ll tell the transport that the handling is successfully done by calling its ack method. Otherwise, we’ll also let the transport know by calling its reject method. In both cases, the transport will remove the message, so it won’t be handled again before the next step. We can additionally add some logging here for better debugging.

use Behat\Behat\Context\Context;
use Behat\Hook\BeforeStep;
use Symfony\Component\Clock\ClockInterface;
use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\MessageBusInterface;

final class BackgroundJobsContext implements Context
{
    public function __construct(
        private Transport $transport,
        private ClockInterface $clock,
        private MessageBusInterface $backgroundJobsBus
    ) {
    }

    #[BeforeStep]
    public function processJobs(): void
    {
        $now = $this->clock->now();

        foreach ($this->transport->get() as $envelope) {
            if ($this->getDispatchTime($envelope) > $now) {
                continue;
            }

            try {
                $this->backgroundJobsBus->dispatch($envelope);

                $this->transport->ack($envelope);
            } catch (\Throwable) {
                $this->transport->reject($envelope);
            }
        }
    }

    private function getDispatchTime(Envelope $envelope): \DateTimeImmutable
    {
        $dispatchAt = $envelope->last(DispatchAtStamp::class);

        return \DateTimeImmutable::createFromTimestamp($dispatchAt->getTimestamp());
    }
}

An important thing to note here is that when injecting the Transport instance in the hook, it is not the same instance that we’ll have within the application itself. While running Behat with the Symfony extension, there will be two separate containers - one for the application, and one for the actual tests.

As described in the extension docs:

That means there is a first instance of your Symfony kernel with a corresponding container, and that instance is used to configure (and possibly autowire) your context classes.

The second instance of the Symfony kernel and its corresponding container is used when you make requests to your application with the symfony Mink driver.

Because of this, if we keep the scheduled messages in memory, the instance of the transport in the context won’t have access to that list.

A possible workaround here is to inject the application’s container in the contexts, but that will work only for scenarios where the Mink driver is used. Also, it can become unreliable if we have scenarios with multiple Mink requests.

When making multiple Mink requests within a single scenario, the second kernel and container (behat.driver.service_container) needs to be reset to provide a clean state for the second and every additional request. This reset will happen immediately before the second and any subsequent request is handed to the kernel. So, while in general it is possible to inspect the driver’s container state after requests, setting it up (bringing it into desired state) easily is only possible for the first request.

Needing to share the scheduled background jobs between the two instances of the transport, we’ll use the Symfony Cache component to temporarily persist them somewhere else.

We’ll start by defining a new cache pool in the test environment (config/packages/test/cache.yaml). In the example here, we’ll use the filesystem adapter.

framework:
    cache:
        pools:
            scheduled_jobs_pool:
                adapter: cache.adapter.filesystem

Next, let’s take a look at the actual implementation of the sender. When a message is dispatched to a message bus, Messenger calls the send method of the sender, and passes the message wrapped in an envelope. Here, we can adjust that envelope as needed, e.g. by adding more stamps to it. In our case we need to add two more stamps.

When scheduling the background jobs in the command handler above, we added DelayStamp with the delay value in milliseconds, relative to the current time. As the current time will be modified when we get the messages from the receiver, we need to keep the actual value of the time when that background job should be handled.

Because of that, we’ll calculate that information, and stick it to the envelope object using a new DispatchAtStamp stamp, as defined here:

use Symfony\Component\Messenger\Stamp\StampInterface;

final readonly class DispatchAtStamp implements StampInterface
{
    public function __construct(
        private int $timestamp
    ) {
    }

    public function getTimestamp(): int
    {
        return $this->timestamp;
    }
}

In a second stamp, which will be an instance of the Symfony\Component\Messenger\Stamp\TransportMessageIdStamp class, we’ll store an ID (which we can generate as an UUID using the Symfony UID component) of the message specific to our transport. We’ll later use that ID to identify the specific envelope when we need to remove the message from the cache.

Finally, we’ll use the Messenger’s serializer service to serialize the envelope (which will also clean it from some non-persistable stamps), and store it in the cache pool.

use Psr\Cache\CacheItemPoolInterface;
use Symfony\Component\Clock\ClockInterface;
use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\Stamp\DelayStamp;
use Symfony\Component\Messenger\Stamp\TransportMessageIdStamp;
use Symfony\Component\Messenger\Transport\Sender\SenderInterface;
use Symfony\Component\Messenger\Transport\Serialization\SerializerInterface;
use Symfony\Component\Uid\Uuid;

final class Sender implements SenderInterface
{
    public function __construct(
        private CacheItemPoolInterface $scheduledJobsPool,
        private ClockInterface $clock,
        private SerializerInterface $serializer
    ) {
    }

    public function send(Envelope $envelope): Envelope
    {
        $dispatchAt = $this->calculateDispatchTime($envelope);
        $messageId = Uuid::v7()->toString();

        $envelope = $envelope->with(
            new DispatchAtStamp($dispatchAt->getTimestamp()),
            new TransportMessageIdStamp($messageId)
        );

        $this->cacheScheduledJob($envelope);

        return $envelope;
    }

    private function calculateDispatchTime(Envelope $envelope): \DateTimeImmutable
    {
        $dispatchAt = $this->clock->now();
        $delayStamp = $envelope->last(DelayStamp::class);

        if ($delayStamp === null) {
            return $dispatchAt;
        }

        $delaySeconds = $delayStamp->getDelay() / 1000;

        return $dispatchAt->modify(
            sprintf("+%d seconds", $delaySeconds)
        );
    }

    private function cacheScheduledJob(Envelope $envelope): void
    {
        $item = $this->scheduledJobsPool->getItem('scheduled_jobs');
        $jobs = $item->isHit() ? $item->get() : [];

        $envelope = $this->serializer->encode($envelope);
        $jobs[] = $envelope;

        $item->set($jobs);

        $this->scheduledJobsPool->save($item);
    }
}

The last part of the process we need to cover is the receiver. As we saw above, the main responsibility of the receiver is to provide the messages stored in the transport to whoever wants to process them. Additionally, it should be able to handle message acknowledges and rejections.

To provide the messages, we’ll read them from the same cache pool as above. Then we’ll deserialize each of them using the same serializer we used in the sender, so we can get them in the form of an envelope again.

An important thing to do here is to add a ReceivedStamp stamp to the envelope. With this stamp added, next time we dispatch the message (in the Behat context above), Messenger will know that it has already been processed by a transport and will directly pass it to the appropriate handler. Without this stamp, the message will again reach the sender and be cached instead of handled.

use Psr\Cache\CacheItemInterface;
use Psr\Cache\CacheItemPoolInterface;
use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\Stamp\ReceivedStamp;
use Symfony\Component\Messenger\Stamp\TransportMessageIdStamp;
use Symfony\Component\Messenger\Transport\Receiver\ReceiverInterface;
use Symfony\Component\Messenger\Transport\Serialization\SerializerInterface;

final class Receiver implements ReceiverInterface
{
    public function __construct(
        private CacheItemPoolInterface $scheduledJobsPool,
        private SerializerInterface $serializer
    ) {
    }

    public function get(): iterable
    {
        return array_map(
            fn(Envelope $envelope) => $envelope->with(
                new ReceivedStamp('time-sensitive-transport')
            ),
            $this->getCachedEnvelopes()
        );
    }

    /** @return Envelope[] */
    private function getCachedEnvelopes(): array
    {
        $item = $this->getCacheItem();
        $envelopes = $item->isHit() ? $item->get() : [];

        return array_map(
            fn(array $envelope) => $this->serializer->decode($envelope),
            $envelopes
        );
    }

    private function getCacheItem(): CacheItemInterface
    {
        return $this->scheduledJobsPool->getItem('scheduled_jobs');
    }

    // ...
}

When acknowledging or rejecting a message, we saw above that we’ll call the ack and reject methods respectively. In them, we’ll share the same logic and we’ll just remove the messages from the cache. During this process, we’ll use the TransportMessageIdStamp stamp we added to each of the messages in the sender, so we can identify and remove the correct message in the cache pool.

use Psr\Cache\CacheItemInterface;
use Psr\Cache\CacheItemPoolInterface;
use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\Stamp\ReceivedStamp;
use Symfony\Component\Messenger\Stamp\TransportMessageIdStamp;
use Symfony\Component\Messenger\Transport\Receiver\ReceiverInterface;
use Symfony\Component\Messenger\Transport\Serialization\SerializerInterface;

final class Receiver implements ReceiverInterface
{
    public function __construct(
        private CacheItemPoolInterface $scheduledJobsPool,
        private SerializerInterface $serializer
    ) {
    }

    // ...

    public function ack(Envelope $envelope): void
    {
        $this->removeFromCache($envelope);
    }

    public function reject(Envelope $envelope): void
    {
        $this->removeFromCache($envelope);
    }

    private function removeFromCache(Envelope $envelope): void
    {
        $cachedEnvelopes = $this->getCachedEnvelopes();
        $idToBeRemoved = $this->getTransportMessageId($envelope);

        $withoutDeleted = array_filter(
            $cachedEnvelopes,
            fn(Envelope $envelope) => $this->getTransportMessageId($envelope) !== $idToBeRemoved
        );

        $serialized = array_map(
            fn(Envelope $envelope) => $this->serializer->encode($envelope),
            $withoutDeleted
        );

        $cacheItem = $this->getCacheItem();
        $cacheItem->set($serialized);

        $this->scheduledJobsPool->save($cacheItem);
    }

    private function getTransportMessageId(Envelope $envelope): string
    {
        return $envelope->last(TransportMessageIdStamp::class)->getId();
    }
}

To ensure that we’ll have an empty list of scheduled jobs before each scenario, we’ll define another hook in which we’ll clear the cache pool.

use Behat\Behat\Context\Context;
use Behat\Hook\BeforeScenario;
use Psr\Cache\CacheItemPoolInterface;

final class CacheContext implements Context
{
    public function __construct(
        private CacheItemPoolInterface $scheduledJobsPool
    ) {
    }

    #[BeforeScenario]
    public function clearCachedMessages(): void
    {
        $this->scheduledJobsPool->clear();
    }
}

If we run the Behat tests again, they will now pass.

Next steps

In this article, we saw how we can get control over which scheduled jobs will be handled and when. If our application is much bigger, checking the cache before each step may become a performance concern, so in such a case we may use Behat tags to mark features/scenarios where this should be applied. The process can also be tweaked to consider retrying strategies, etc.

At the time of writing, the current versions are PHP 8.4, Symfony 7.3, and Behat 3.23.

Photo for social media by Nur Yilmaz.

Resolving values for unmapped properties when mapping request data to DTOs in Symfony 6.3+

Thu, 01 Jun 2023 21:00:00 +0200

Ever since it was introduced, the functionality for mapping request data to DTOs has been my favourite Symfony 6.3 new feature. The new #[MapRequestPayload] and #[MapQueryString] attributes allow us to delegate the DTO instantiation to the framework, instead of doing it manually in the controllers - for example when instantiating commands to be dispatched to a command bus. However, I realized that most of the commands in my application contain additional properties which are not directly mapped to the request data - such as the ID of the currently authenticated user. In this article, we’ll see how we can enhance the process to be able to resolve the unmapped values in such cases.

Let’s start with this command:

readonly class ReserveRoomCommand
{
    public function __construct(
        public string $customerId,
        public string $roomId,
        public DateTimeImmutable $reservationFrom,
        public DateTimeImmutable $reservationTo
    ) {
    }
}

Usually, when we want to dispatch an instance of the command from a controller, we’d manually retrieve the values from the request object, and use them to initiate the command object:

#[Route("/reservations")]
class ReservationsController extends AbstractController
{
    #[Route("/", methods: "POST")]
    public function reserve(Request $request): Response
    {
        $command = new ReserveRoomCommand(
            $request->request->get('customerId'),
            $request->request->get('roomId'),
            new \DateTimeImmutable($request->request->get('from')),
            new \DateTimeImmutable($request->request->get('to'))
        )

        // ... dispatch the command, etc.
    }
}

With the new #[MapRequestPayload] attribute provided by Symfony, this process is now automated, and we can replace the Request argument of the controller method with an argument of the command class. Additionally, we need to declare the new attribute on the argument.

Note: We will only use #[MapRequestPayload] in this article, but the same applies when using the #[MapQueryString] attribute too. The framework uses the same value resolver for attributes with any of these attributes.

#[Route("/reservations")]
class ReservationsController extends AbstractController
{
    #[Route("/", methods: "POST")]
    public function reserve(
        #[MapRequestPayload] ReserveRoomCommand $command
    ): Response {
        // ... dispatch the command, etc.
    }
}

So, the framework will instantiate the object for us and populate it with the data from the request. But what if we don’t want to read the customerId value form the request, but use the ID of the authenticated customer instead?

Although customizable, by default the framework uses the \Symfony\Component\HttpKernel\Controller\ArgumentResolver\RequestPayloadValueResolver value resolver when resolving controller action arguments like the command object above.

If we take a look at that resolver, we can see that it simply reads the request content (either from the query string or the payload) and passes it to the Serializer component. The serializer decodes the data if needed (e.g. if the data is sent as a JSON object) - turning it into an associative array, and then denormalizes it - turning it into an object of the desired class, in our case ReseveRoomCommand.

In our case, the customerId property of the command doesn’t have a default value, so if we don’t supply it within the request, the denormalization process will fail.

Failed to create object because the class misses the “customerId” property.
^{PartialDenormalizationException}

To avoid this, but to also protect the value from being set from outside, we’ll need to hook into the denormalization process and modify the data by adding/replacing the needed items.

First, let’s create a new denormalizer.

use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;

class PropertyValueResolvingDenormalizer implements DenormalizerInterface
{
    public function denormalize(mixed $data, string $type, string $format = null, array $context = []): mixed { ... }

    public function supportsDenormalization(mixed $data, string $type, string $format = null): bool { ... }

    public function getSupportedTypes(?string $format): array { ... }
}

We only want to resolve values for some properties, and not all of them can be resolved in the same way. To achieve the differentiation, we can create new (or reuse some existing) custom attributes for each case, e.g. for resolving the ID of the authenticated customer.

#[\Attribute(\Attribute::TARGET_PROPERTY)]
class Authenticated
{
}

And declare it on the argument in the command:

readonly class ReserveRoomCommand
{
    public function __construct(
        #[Authenticated] public string $customerId,
        public string $roomId,
        public DateTimeImmutable $from,
        public DateTimeImmutable $to,
    ) {
    }
}

As already mentioned, we can have multiple similar attributes and multiple ways for resolving values, so we can define the following interface and have all the resolves implement it:

use Symfony\Component\DependencyInjection\Attribute\AutoconfigureTag;

#[AutoconfigureTag]
interface PropertyValueResolverInterface
{
    public function resolve(ReflectionAttribute $attribute): mixed;

    /** @return class-string */
    public function supportedAttribute(): string;
}

Note: For simplicity, we'll use attributes to interact with the Symfony's Dependency Injection container. You can still use your preferred way for configuring it.

To resolve values for arguments marked with our #[Authenticated] attribute, we’ll have an implementation that will support that attribute, and which will be fetching the current customer and returning its ID.

class AuthenticatedUserResolver implements PropertyValueResolverInterface
{
    // ...

    public function resolve(ReflectionAttribute $attribute): mixed
    {
        $uuid = // resolve the authenticated customer's uuid using some other service

        return $uuid;
    }

    public function supportedAttribute(): string
    {
        return Authenticated::class;
    }
}

Back to the denormalizer, we’ll be injecting an array of all registered value resolvers implementing the interface from above. Then in the supportsDenormalization we can use this list to determine if the denormalizer should be applied when mapping some request data.

Among the other arguments we’re receiving in the supportsDenormalization method is the type i.e. the class of the object we’ll be getting at the end of the process - in our case the command. From that class, we can get the list of properties and then iterate over it to find if any of the properties has a declared attribute for which we have a suitable value resolver. If we find such property, we’ll let the serializer know that it should use this denormalizer.

use Symfony\Component\DependencyInjection\Attribute\TaggedIterator;
use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;

class PropertyValueResolvingDenormalizer implements DenormalizerInterface
{
    /** @var array<class-string, object<PropertyValueResolverInterface>> */
    private array $resolvers = [];

    /** @param iterable<PropertyValueResolverInterface> $resolvers */
    public function __construct(
        #[TaggedIterator(PropertyValueResolverInterface::class)] iterable $resolvers
    ){
        foreach ($resolvers as $resolver) {
            $this->resolvers[$resolver->supportedAttribute()] = $resolver;
        }
    }

    public function supportsDenormalization(mixed $data, string $type, string $format = null): bool
    {
        $properties = (new ReflectionClass($type))->getProperties();

        foreach ($properties as $property) {
            if ($this->canResolveValueForProperty($property)) {
                return true;
            }
        }

        return false;
    }

    private function canResolveValueForProperty(ReflectionProperty $property): bool
    {
        $attributes = $property->getAttributes();

        foreach ($attributes as $attribute) {
            if (array_key_exists($attribute->getName(), $this->resolvers)) {
                return true;
            }
        }

        return false;
    }

    // ...
}

In the denormalize method we’ll be doing something similar - we can iterate over the class’s properties as we did above, and use a suitable value resolver for each of the properties that need resolving. In the data argument we’ll have the existing request data - which have previously been decoded by the serializer - as an array that we can modify to add/replace the resolved values.

As our intention is not to completely replace the denormalization process, but just to enhance it, we’ll pass the final modified data array to the serializer’s ObjectNormalizer which will then transform it into an object.

use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;
use Symfony\Component\Serializer\Normalizer\ObjectNormalizer;

class PropertyValueResolvingDenormalizer implements DenormalizerInterface
{
    // ...

    private ObjectNormalizer $objectNormalizer;

    public function __construct(
        // ...
        ObjectNormalizer $objectNormalizer,
    ) {
        // ...
        $this->objectNormalizer = $objectNormalizer;
    }

    public function denormalize(mixed $data, string $type, string $format = null, array $context = []): mixed
    {
        $properties = (new ReflectionClass($type))->getProperties();

        foreach ($properties as $property) {
            $name = $property->getName();

            if (!$this->canResolveValueForProperty($property)) { // shown in code above
                continue;
            }

            $data[$name] = $this->resolveValueForProperty($property);
        }

        return $this->objectNormalizer->denormalize($data, $type, $format, $context);
    }

    private function resolveValueForProperty(ReflectionProperty $property): mixed
    {
        $attributes = $property->getAttributes();

        foreach ($attributes as $attribute) {
            if (array_key_exists($attribute->getName(), $this->resolvers)) {
                return $this->resolvers[$attribute->getName()]->resolve($attribute);
            }
        }

        return null;
    }

    // ...
}

Finally, let’s also look at the getSupportedTypes method. It has been introduced in Symfony 6.3 too as a performance improvement, but due to BC reasons is still not enforced as part of the DenormalizerInterface interface. It is also a replacement for the now-deprecated \Symfony\Component\Serializer\Normalizer\CacheableSupportsMethodInterface interface and can be used to tell the serializer whether it can cache the result of the supportsDenormalization method when denormalizing into a certain type.

As our denormalizer can process data for multiple types - objects of multiple classes, and the declared attributes are not changing during the execution, we can use the generic object type and always allow the caching.

You can read more about the getSupportedTypes in this article.

use Symfony\Component\Serializer\Normalizer\DenormalizerInterface;

class PropertyValueResolvingDenormalizer implements DenormalizerInterface
{
    // ...

    /** @return array<class-string, bool> */
    public function getSupportedTypes(?string $format): array
    {
        return ['object' => true];
    }
}

The whole PropertyValueResolvingDenormalizer class is available here.

To try the denormalizer out, let’s say that the ID of the authenticated customer is “customer-uuid”. If we send a request with the following JSON body to our endpoint:

{
    "roomId": "room-uuid",
    "from": "2023-06-10",
    "to": "2023-06-15"
}

We’ll get the following object as a result:

^ ReserveRoomCommand {#181
    +customerId: "customer-uuid"
    +roomId: "room-uuid"
    +from: DateTimeImmutable @1686355200 {#182
        date: 2023-06-10 00:00:00.0 UTC (+00:00)
    }
    +to: DateTimeImmutable @1686787200 {#209
        date: 2023-06-15 00:00:00.0 UTC (+00:00)
    }
}

As another example, let’s imagine that for some reason we also want to pass the reservation time within the command, which will be the current time.

Now we just need to create a new (or re-use an existing) attribute:

#[\Attribute(\Attribute::TARGET_PROPERTY)]
class CurrentDateTime
{
}

And a resolver for it:

use Psr\Clock\ClockInterface;

class CurrentDateTimeResolver implements PropertyValueResolverInterface
{
    private ClockInterface $clock;

    public function __construct(ClockInterface $clock)
    {
        $this->clock = $clock;
    }

    public function resolve(ReflectionAttribute $attribute): mixed
    {
        return $this->clock->now()->format(DATE_ATOM);
    }

    public function supportedAttribute(): string
    {
        return CurrentDateTime::class;
    }
}

Note that here we’re returning a string as a resolved value, and not a DateTimeImmutable object. That’s because after we pass the data to the ObjectNormalizer to continue with the denormalization, it will use the \Symfony\Component\Serializer\Normalizer\DateTimeNormalizer denormalizer to instantiate the final DateTimeImmmutable object - and that denormalizer requires the value to be sent as a string. So, in general, our value resolvers should be returning the resolved values just as if they’ve been send within a request.

Now if we add a new property to the command and declare the attribute on it:

readonly class ReserveRoomCommand
{
    public function __construct(
        #[Authenticated] public string $customerId,
        public string $roomId,
        public DateTimeImmutable $from,
        public DateTimeImmutable $to,
        #[CurrentDateTime] public DateTimeImmutable $reservedAt
    ) {
    }
}

When we send the same JSON object as a request as above, we’ll get the current time as expected:

^ ReserveRoomCommand {#184
    +customerId: "customer-uuid"
    +roomId: "room-uuid"
    +from: DateTimeImmutable @1686355200 {#185
        date: 2023-06-10 00:00:00.0 UTC (+00:00)
    }
    +to: DateTimeImmutable @1686787200 {#213
        date: 2023-06-15 00:00:00.0 UTC (+00:00)
    }
    +reservedAt: DateTimeImmutable @1685054767 {#214
        date: 2023-05-25 22:46:07.0 +00:00
    }
}

As a next step, we can declare the attributes on all the commands or other objects we want to be mapped in the controllers. If we face another unmapped property, we saw how we can add a custom resolver for it.

Photo for social media by Daria Obymaha.

Centralized exception handling with Symfony and custom PHP attributes

Thu, 24 Nov 2022 18:02:00 +0100

Over time, as our application grows, the controllers can become cluttered with repeated exception handling code. In this article we’ll see how we can have both cleaner controller methods when using the Symfony framework by centralizing the exception handling, and cleaner domain exceptions by only declaring custom PHP attributes on their classes.

Let’s imagine that we are developing an e-commerce application that can process and manage orders made by the website’s visitors. One of the functionalities is the ability to cancel a specific order. However, an order can be cancelled only if these three conditions are satisfied:

it must be present (obviously)
it must not be shipped yet
only the customer who created it can cancel it

If there is an attempt to cancel an order without satisfying all the conditions, we are throwing one of the following exceptions:

class OrderNotFound extends Exception
{
    public function __construct(OrderId $id)
    {
        parent::__construct(
            sprintf('The order "%s" could not be found.', (string) $id)
        );
    }
}

class OrderAlreadyShipped extends Exception
{
    public function __construct(Order $order)
    {
        parent::__construct(
            sprintf('The order "%s" is already shipped.', (string) $order->getId())
        );
    }
}

class CustomerMismatch extends Exception
{
    public function __construct(Order $order, Customer $customer)
    {
        parent::__construct(sprintf(
            'The order "%s" is not created by the customer "%s".',
            (string) $order->getId(),
            (string) $customer->getId()
        ));
    }
}

Cancelling the order and handling the exceptions

One way to handle the possibly thrown exceptions is to catch them in the controller where we initiate the cancellation (either directly or through some other service, like a command handler). Then we can build the response, assign the suitable status code to it, and return it to the client.

class OrdersController
{
    // ...

    #[Route("/orders/{id}/cancel", ...)]
    public function cancel(string $id): Response
    {
        // ...

        try {
            $order = $this->orders->find($id);
            $order->cancel(by: $customer);

            $this->orders->store($order);
        } catch (OrderNotFound $e) {
            return new JsonResponse(["error" => $e->getMessage()], Response::HTTP_NOT_FOUND);
        } catch (CustomerMismatch $e) {
            return new JsonResponse(["error" => $e->getMessage()], Response::HTTP_FORBIDDEN);
        } catch (OrderAlreadyShipped $e) {
            return new JsonResponse(["error" => $e->getMessage()], Response::HTTP_UNPROCESSABLE_ENTITY);
        }

        return new JsonResponse(...);
    }
}

As we can see, most of the code in our method is used for handling the exceptions. This will likely happen with most of the other controller methods in our application as well. Another negative implication is that whenever we start throwing a new similar exception somewhere in our domain layer, we’ll also have to add another catch block in all controllers it may end up to. That can span over multiple API endpoints, thus we’ll need to update multiple controller methods (for example, we may also throw an OrderAlreadyShipped exception if somebody tries to add a new item to an already shipped order.)

Moving the exception handling

As a first step, let’s remove the entire try-catch block from the controller method:

class OrdersController extends AbstractController
{
    // ...

    #[Route("/orders/{id}/cancel", ...)]
    public function cancel(string $id): Response
    {
        // ...

        $order = $this->orders->find($id);
        $order->cancel(by: $customer);

        $this->orders->store($order);

        return new JsonResponse(...);
    }
}

The controller method is more clear now, and we can easily see it’s intention. Note that as a trade-off, we’re losing some visibility over what can go wrong during the execution of the methods we’re calling.

If we try to cancel an already shipped order now, as expected since we removed the exception handling, we’ll get the Symfony’s default error page.

The order “213ba2c0-d82c-4805-8de4-773d20f3cbe3” is already shipped.
^{HTTP 500 Internal Server Error - OrderAlreadyShipped}

When an exception is thrown during the handling of the request, and is not explicitly caught and handled, the Symfony’s HttpKernel dispatches an kernel.exception event.

To centralize the exception handling, we can create a listener that will listen to this type of events, and that will take care of preparing the response for the client. When such event is dispatched, all listeners that are supposed to handle it receive an instance of the ExceptionEvent class, from which we can get the thrown exception object.

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use Symfony\Component\HttpKernel\KernelEvents;

class ExceptionHandler implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [KernelEvents::EXCEPTION => 'handleException'];
    }

    public function handleException(ExceptionEvent $event): void
    {
        $exception = $event->getThrowable();

        // ...
    }
}

Now, whenever there’s an unhandled exception in our application, we will receive an event in the listener we just created. However, we don’t want all the exceptions handled here, as not everything is intended to be shown to the client, so we need a way to determine if the received exception should be handled or not.

The domain exceptions we have in our application so far can be divided in 3 groups, each associated with an appropriate HTTP status code.

Exception	Status Code
OrderNotFound	404 Not Found
CustomerMismatch	403 Forbidden
OrderAlreadyShipped	422 Unprocessable Entity

For each of the HTTP status codes that we want to support we’ll create a separate custom PHP attribute. To make sure all of them are providing a specific status code, the attributes will implement the following interface:

interface StatusCodeProvider
{
    public function getStatusCode(): int;
}

Here are the three attributes we need so far:

use Symfony\Component\HttpFoundation\Response;

#[Attribute(Attribute::TARGET_CLASS)]
class NotFound implements StatusCodeProvider
{
    public function getStatusCode(): int
    {
        return Response::HTTP_NOT_FOUND;
    }
}

use Symfony\Component\HttpFoundation\Response;

#[Attribute(Attribute::TARGET_CLASS)]
class UnprocessableEntity implements StatusCodeProvider
{
    public function getStatusCode(): int
    {
        return Response::HTTP_UNPROCESSABLE_ENTITY;
    }
}

use Symfony\Component\HttpFoundation\Response;

#[Attribute(Attribute::TARGET_CLASS)]
class AccessDenied implements StatusCodeProvider
{
    public function getStatusCode(): int
    {
        return Response::HTTP_FORBIDDEN;
    }
}

Next, we’ll declare the new attributes on the existing exception classes:

#[NotFound]
class OrderNotFound extends Exception { ... }

#[UnprocessableEntity]
class OrderAlreadyShipped extends Exception { ... }

#[AccessDenied]
class CustomerMismatch extends Exception { ... }

Back to the listener, we can now use the Reflection API to get the attributes declared on the thrown exception’s class. As any class can have multiple attributes declared on it, we can use the fact that all our attributes implement the StatusCodeProvider interface and filter out the non-related ones. If no such attribute is declared on the class, it means that we don’t support handling this exception in the handler. If multiple such attributes are declared, we’ll just use the first one.

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;

class ExceptionHandler implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array { ... }

    public function handleException(ExceptionEvent $event): void { ... }

    private function getAttribute(Throwable $exception): ?StatusCodeProvider
    {
        $reflectionClass = new ReflectionClass($exception);
        $attributes = $reflectionClass->getAttributes();

        $instances = array_map(
            fn(ReflectionAttribute $attribute) => $attribute->newInstance(),
            $attributes
        );

        $supported = array_filter(
            $instances,
            fn(object $attribute) => $attribute instanceof StatusCodeProvider
        );

        if (count($supported) === 0) {
            return null;
        }

        return $supported[array_key_first($supported)];
    }

    private function supportedException(Throwable $exception): bool
    {
        return $this->getAttribute($exception) !== null;
    }
}

If the exception is not supported, we can simply ignore it and let it be handled somewhere else. Otherwise, we need to extract the needed data and build the response we’d want to return to the client.

For the response’s content we can use the message provided by the exception, and we can get the needed HTTP status code from the declared attribute that we fetched above.

When the response is prepared, we need to pass it along by updating the received event object using the setResponse method.

Note: By default we can only set 3xx (Redirection), 4xx (Client error) and 5xx (Server error) HTTP status codes on the response we're building in the listener. If we set a status code that is outside these ranges, the HttpKernel will override it and will use 500 instead.
This behaviour can be changed by calling allowCustomResponseCode() on the event object, but doing that is discouraged by the docs.

use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;

class ExceptionHandler implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array { ... }

    public function handleException(ExceptionEvent $event): void
    {
        $exception = $event->getThrowable();

        if (!$this->supportedException($exception)) {
            return;
        }

        $attribute = $this->getAttribute($exception);

        $response = new JsonResponse(
            [
                "error" => $exception->getMessage()
            ],
            $attribute->getStatusCode()
        );

        $event->setResponse($response);
    }

    private function getAttribute(Throwable $exception): ?StatusCodeProvider { ... }

    private function supportedException(Throwable $exception): bool { ... }
}

Note: For simplicity, the data for the response's content in the examples is passed directly as an array. An external serializer service can be injected and used to structure the data instead.

If we try to cancel the same order again, this time we’ll get the expected JSON data, with 422 Unprocessable Entity as status code.

{
    "error": "The order \"213ba2c0-d82c-4805-8de4-773d20f3cbe3\" is already shipped."
}

Next steps

Now that we have the attributes for adding the needed metadata, and the handler which will handle the marked exceptions, we can easily add more use cases.

For example, if we have a functionality for applying promo codes to the orders, and we check if the given code is still valid, we can have the following exception, and just declare the UnprocessableEntity attribute on it:

#[UnprocessableEntity]
class PromoCodeExpired extends Exception
{
    public function __construct(PromoCode $promoCode)
    {
        parent::__construct(sprintf(
            'The promo code "%s" has expired.',
            $promoCode->getCode()
        ));
    }
}

If we want to support more status codes, we only need to create a new attribute that will implement the StatusCodeProvider interface and start declaring it on the exceptions.

Sometimes, it may happen that we may want to return a different message to the client instead of the one we have in the exception (which we may still want to keep for other purposes). For such cases, we can extend the attributes by adding an optional message argument to each of them that can be specified when declaring it on an exception. Then in the handler we can use this message if provided, or the exception’s one if not.

The events of the ExceptionEvent class also contain the request object, which can be useful to decide in which format we should respond to the client. If we also have controllers that render templates and provide HTML content, we can create an additional error handler that will set a flash message and redirect the client to the previous page, if the exception is thrown while executing a request from those pages. This can be also useful if we have multiple bounded contexts, so we can have multiple similar handlers that will cover exceptions from different areas in the application.

Photo for social media by Vie Studio.

Experimental: Unpacking message properties as handler arguments in Symfony Messenger

Tue, 10 May 2022 22:29:00 +0200

In my previous post, we saw that by using custom PHP attributes, we can have our Symfony Messenger message handlers placed in any service in our application. The only requirement for the message handlers is for them to be methods that are able to receive the message object as an argument. In this post we will see how we can avoid that requirement, and register any method as a message handler, by automatically passing any of the message’s properties as values for the handler’s arguments.

Warning: I got this idea while working on a hobby project that will never go to production. I haven't tried it in a real-world project and haven't really thought of the long-term consequences of it.
My advice is to use what you'll read here only as a basis for future experimentation, and not as a final solution.

We can start by declaring two message busses in our application, called event_bus and command_bus:

framework:
    messenger:
        buses:
            event_bus: ...
            command_bus: ...

Imagine that we have a store where people can buy and sell books. Whenever somebody buys a book, we’ll be dispatching the following domain event:

class BookWasPurchased
{
    public function __construct(
        public readonly string $title,
        public readonly string $customerName,
        public readonly DateTimeInterface $purchasedAt
    ) {
    }
}

We have a PurchaseHistory service that keeps track who has bought which book, so we want its recordPurchase, which requires the title of the book and the name of the customer, to be called whenever this event occurs.

class PurchaseHistory
{
    public function recordPurchase(string $bookTitle, string $customerName): void
    {
        dd(sprintf(
            "%s bought the \"%s\" book.",
            $customerName,
            $bookTitle
        ));
    }
}

To achieve that, we need to register a listener that will be receiving and handling these events:

class RecordBookPurchase
{
    private PurchaseHistory $purchaseHistory;

    public function __construct(PurchaseHistory $purchaseHistory)
    {
        $this->purchaseHistory = $purchaseHistory;
    }

    #[Listener(event: BookWasPurchased::class)]
    public function handle(BookWasPurchased $event): void
    {
        $this->purchaseHistory->recordPurchase(
            $event->title,
            $event->customerName
        );
    }
}

As we can see here, we’re not doing much in this listener besides getting the needed information from the event’s properties and passing it to the service where the actual recording will happen.

Let’s see how we can avoid having to create separate classes/methods for this type of listeners, and just register the actual service’s method as a message handler (an event listener in our case) instead.

As a first step, we’ll remove the RecordBookPurchase class and move the listener attribute declaration to the PurchaseHistory::recordPurchase method:

class PurchaseHistory
{
    #[Listener(event: BookWasPurchased::class)]
    public function recordPurchase(string $bookTitle, string $customerName): void
    {
        // ...
    }
}

And then dispatch an instance of the event:

$eventBus->dispatch(
    new BookWasPurchased('Example Book', 'John Smith', $now)
);

As expected, the handling of the event will fail because we broke the compatibility - the handler is expecting multiple string arguments, but it receives an BookWasPurchased instance instead.

Handling “BookWasPurchased” failed: PurchaseHistory::recordPurchase(): Argument #1 ($bookTitle) must be of type string, BookWasPurchased given
^{TypeError > HandlerFailedException}

So, we need to find a way and build some mechanism that will transform the data before it arrives to the handler.

Replacing the handlers locator

When a message is dispatched to a Symfony Messenger message bus, it goes through a list of middleware before eventually being handled by a handler. The last middleware in the list, \Symfony\Component\Messenger\Middleware\HandleMessageMiddleware, is the one that calls the appropriate handler(s).

This middleware uses a service that implements the \Symfony\Component\Messenger\Handler\HandlersLocatorInterface interface to find all the registered handlers for the current dispatched message.

If we take a look at that interface, its getHandlers method expects the message wrapped in an Envelope (that’s how it’s already being received in middleware) and returns an iterable that consists of \Symfony\Component\Messenger\Handler\HandlerDescriptor objects (we’ll call them handler descriptors). Each of these handler descriptors wraps a found handler, as well as some additional metadata related to it.

interface HandlersLocatorInterface
{
    /**
    * Returns the handlers for the given message name.
    *
    * @return iterable<int, HandlerDescriptor>
    */
    public function getHandlers(Envelope $envelope): iterable;
}

Within the middleware, from each of the handler descriptors, the actual handler is being retrieved and called with the message object as an argument.

// from the \Symfony\Component\Messenger\Middleware\HandleMessageMiddleware class

foreach ($this->handlersLocator->getHandlers($envelope) as $handlerDescriptor) {
    // ...

    $handler = $handlerDescriptor->getHandler();

    // ...
    
    $result = $handler($message);
                
    // ...
}

If we take a look at the handler descriptor for the handler we defined here, we can see that it has the handler as a closure, with both the string arguments.

Symfony\Component\Messenger\Handler\HandlerDescriptor {#618 ▼
    -handler: PurchaseHistory::recordPurchase(string $bookTitle, string $customerName): void {#620 ▶}
    -name: "PurchaseHistory::recordPurchase"
    -batchHandler: null
    -options: array:1 [▼
        "method" => "recordPurchase"
    ]
}

To make it possible for the middleware to call our method as a handler, we can wrap it in another closure with the message as an argument, or with no arguments at all.

To do that, we will create a new implementation of the locator interface which will decorate the existing one provided by the component, and which will wrap the found handlers if needed.

For now, let’s only create the decorator and return any result that we’ll get from the decorated class.

use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\Handler\HandlersLocatorInterface;

class WrappingHandlersLocator implements HandlersLocatorInterface
{
    private HandlersLocatorInterface $decorated;

    public function __construct(HandlersLocatorInterface $decorated)
    {
        $this->decorated = $decorated;
    }

    public function getHandlers(Envelope $envelope): iterable
    {
        return $this->decorated->getHandlers($envelope);
    }
}

Next, we need to make the middleware use our decorator as a locator instead of the component’s one (that we’re decorating).

The Messenger component uses the \Symfony\Component\Messenger\DependencyInjection\MessengerPass compiler pass to register its internal services in the application’s service container. There, we can see that it will register separate services of both the middleware and the handlers locator for each of the message busses that we have:

// from the \Symfony\Component\Messenger\DependencyInjection\MessengerPass class

// ...

foreach ($busIds as $bus) {
    $container->register($locatorId = $bus.'.messenger.handlers_locator', HandlersLocator::class)
        ->setArgument(0, $handlersLocatorMappingByBus[$bus] ?? [])
    ;

    if ($container->has($handleMessageId = $bus.'.middleware.handle_message')) {
        $container->getDefinition($handleMessageId)
            ->replaceArgument(0, new Reference($locatorId))
        ;
    }
}

// ...

As we created two message busses at the beginning of the article (command_bus and event_bus), we can confirm that we have two services for the handlers locator in the container:

------------------------------------------- -------------------------------------------
Service ID                                  Class name
------------------------------------------- ------------------------------------------- 
command_bus.messenger.handlers_locator      Symfony\Component\Messenger\Handler\HandlersLocator
event_bus.messenger.handlers_locator        Symfony\Component\Messenger\Handler\HandlersLocator
...

Now we need a new compiler pass that will also register our locator implementation as a separate service for each of the busses. Each of the new services should also be marked as decorator that will decorate the existing locator service for the appropriate bus. We also need the new services marked as autowired, so they will get the appropriate locator instance injected when instantiated.

Each of the busses that we have registered in the container is tagged with the messenger.bus tag, so we can use that to find the list of ids of the message bus services.

use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;

class HandlersLocatorCompilerPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        $busses = $container->findTaggedServiceIds('messenger.bus');
        $busIds = array_keys($busses);
    
        foreach ($busIds as $busId) {
            $decoratorId = $busId . '.messenger.wrapping_handlers_locator';
            $originalLocatorId = $busId . '.messenger.handlers_locator';
            
            $container->register($decoratorId, WrappingHandlersLocator::class)
                ->setAutowired(true)
                ->setDecoratedService($originalLocatorId);
        }
    }
}

Finally, we need to register the compiler pass in the application’s kernel:

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\HttpKernel\Kernel as BaseKernel;

class Kernel extends BaseKernel
{
    // ...

    protected function build(ContainerBuilder $container): void
    {
        // ...

        $container->addCompilerPass(new HandlersLocatorCompilerPass());
    }
}

Let’s take a look at the list of services now:

-------------------------------------------             -------------------------------------------
Service ID                                              Class name
-------------------------------------------             ------------------------------------------- 
command_bus.messenger.handlers_locator                  alias for "command_bus.messenger.wrapping_handlers_locator"
command_bus.messenger.wrapping_handlers_locator         WrappingHandlersLocator
command_bus.messenger.wrapping_handlers_locator.inner   Symfony\Component\Messenger\Handler\HandlersLocator

event_bus.messenger.handlers_locator                    alias for "event_bus.messenger.wrapping_handlers_locator"
event_bus.messenger.wrapping_handlers_locator           WrappingHandlersLocator
event_bus.messenger.wrapping_handlers_locator.inner     Symfony\Component\Messenger\Handler\HandlersLocator
...

As we saw in the MessengerPass compiler pass above, each service of the HandleMessageMiddleware class ([bus id].middleware.handle_message) will receive the appropriate [bus id].messenger.handlers_locator service as argument in the constructor. For example, when instantiating the event_bus.middleware.handle_message service, the container will pass the event_bus.messenger.handlers_locator service as an argument.

With the compiler pass that we just registered, we changed, for example, the event_bus.messenger.handlers_locator service to be an alias for our own implementation of the locator, meaning that the component’s middleware will now be getting an instance of our locator.

We can confirm that by checking the instance received in the middleware:

WrappingHandlersLocator {#239 ▼
    -decorated: Symfony\Component\Messenger\Handler\HandlersLocator {#237 ▶}
}

Resolving the values for the arguments

Now that we’re in control of how the handlers will be found, we need to actually implement the getHandlers method.

We already saw that we can get the list of handlers for the dispatched message by using the decorated locator. After that, we can iterate over that list, wrap each of the handlers if needed and then yield it.

For now, we’ll assume that the dispatched message/event contains enough data for the handler’s arguments. Later we’ll see what we can do for other cases as well.

// inside the WrappingHandlersLocator class:

public function getHandlers(Envelope $envelope): iterable
{
    /** @var iterable<int, HandlerDescriptor> $handlerDescriptors */
    $handlerDescriptors = $this->decorated->getHandlers($envelope);
    $message = $envelope->getMessage();

    foreach ($handlerDescriptors as $handlerDescriptor) {
        if ($this->shouldWrapHandler($handlerDescriptor, $message)) {
            yield $this->wrapHandler($handlerDescriptor, $message);
        } else {
            yield $handlerDescriptor;
        }
    }
}

To determine if a handler should we wrapped, we’ll be checking its list of arguments. Basically, we won’t wrap a handler only if it has a single argument type-hinted with the message’s own class. These handlers should continue to be called as before.

// inside the WrappingHandlersLocator class:

private function shouldWrapHandler(HandlerDescriptor $handlerDescriptor, object $message): bool
{
    $arguments = $this->getHandlerArguments($handlerDescriptor);

    return (count($arguments) == 0)
            || (count($arguments) > 1)
            || (!$arguments[0]->getType()->getName() == get_class($message));
}

We already saw that the handler, which we can get from the handler descriptor is a closure, so we can use it to create a ReflectionFunction object. From that object we can get a list of ReflectionParameter objects that will represent the arguments of the handler.

// inside the WrappingHandlersLocator class:

/** @return array<int, ReflectionParameter> */
private function getHandlerArguments(HandlerDescriptor $handlerDescriptor): array
{
    $function = new ReflectionFunction($handlerDescriptor->getHandler());

    return $function->getParameters();
}

To do the wrapping, we need the list of arguments expected by the handler, and values for each of them. After that, we will create a new handler descriptor which, as we saw before, will be yielded instead of the original one.

When creating the new handler descriptor, we’ll pass a new closure with no arguments, which internally will call the original one with the resolved values as arguments.

// inside the WrappingHandlersLocator class:

private function wrapHandler(HandlerDescriptor $handlerDescriptor, object $message): HandlerDescriptor
{
    $handlerArguments = $this->getHandlerArguments($handlerDescriptor);
    $handlerArgumentValues = $this->resolveValuesForHandlerArguments($handlerArguments, $message);

    return new HandlerDescriptor(
        fn() => $handlerDescriptor->getHandler()(...$handlerArgumentValues),
        [
            'alias' => $this->generateHandlerAlias($handlerDescriptor)
        ]
    );
}

As we saw before, in each of the handler descriptors, we have a name for the handler. After a handler finishes handling a message, the HandleMessageMiddleware middleware adds a new \Symfony\Component\Messenger\Stamp\HandledStamp stamp to the envelope that wraps the message, with the name of the handler. The same middleware also checks the received messages for the same type of stamp in order to prevent any of the handlers to handle the same message twice.

In our case, if we wrap multiple handlers, all the newly created handlers will have “Closure” as a name by default. That will prevent the message to be handled by multiple handlers (e.g. if we have multiple listeners), even thought they are completely different ones.

It is not possible to change the name of the handler completely, but there’s an option to submit an alias when creating the handler descriptor. That alias is later used as part of the name, so each handler will be treated as unique.

// inside the WrappingHandlersLocator class:

private function generateHandlerAlias(HandlerDescriptor $handlerDescriptor): string
{
    $function = new ReflectionFunction($handlerDescriptor->getHandler());

    return sprintf(
        "%s::%s",
        $function->getClosureScopeClass()?->getShortName(),
        $function->getName()
    );
}

We already have the mechanism for getting the list of arguments, so now we need to resolve the values, by mapping each of them to some properties of the message.

// inside the WrappingHandlersLocator class:

/**
 * @param array<int, ReflectionParameter> $arguments
 * @return array<int, mixed>
 */
private function resolveValuesForHandlerArguments(array $arguments, object $message): array
{
    return array_map(
        fn(ReflectionParameter $argument) => $this->resolveValueForHandlerArgument($argument, $message),
        $arguments
    );
}

The event that we’re dispatching has more properties than we need in the handler, and additionally, one of the properties has a different name than the handler’s argument. Because of that, we need a way to help the locator to map the properties to the arguments properly, so we’ll create a new PHP attribute called, for example, ExtractedValue.

We’ll be declaring this attribute on those arguments in the handler’s signature that have no matching property in the handled message with same name, or if we intentionally want to use another one. It will have a messageProperty string property that we’ll use to indicate which property of the message should be used for that particular argument. As the property will be optional, we’ll be able to declare the attribute on an argument even if we don’t want to explicitly specify a property name.

use Attribute;

#[Attribute(Attribute::TARGET_PARAMETER)]
class ExtractedValue
{
    public function __construct(
        public readonly ?string $messageProperty = null
    ) {
    }
}

In our case, we’ll be passing the event’s $title property as a value for the $bookTitle argument, so we will declare the attribute on the argument, and we’ll specify the property name. As the $customerName argument can be automatically mapped to the customerName property of the event, we can choose whether to declare the attribute with no arguments, or to just omit it.

class PurchaseHistory
{
    #[Listener(event: BookWasPurchased::class)]
    public function recordPurchase(
        #[ExtractedValue(messageProperty: "title")] string $bookTitle,
        #[ExtractedValue] string $customerName // we could omit the attribute here
    ): void {
        // ...
    }
}

Back to the locator, where we need to resolve the values for each of the attributes. When resolving the value for a single attribute, we’ll first try to fetch the declared ExtractedValue attribute.

If there’s such attribute declared, we’ll check if it contains a specified property name. In the cases when there is no attribute or no method name has been explicitly specified, we’ll assume that we need to use the argument’s name.

Now that we have the needed property name, we’ll try to fetch its value from the message object. If there’s no such property we’ll throw an exception.

// inside the WrappingHandlersLocator class:

private function resolveValueForHandlerArgument(
    ReflectionParameter $argument,
    object $message
): mixed {
    $attribute = $this->getAttributeForArgument($argument);

    $messagePropertyName = $attribute?->messageProperty ?? $argument->getName();

    if (property_exists($message, $messagePropertyName)) {
        return $message->{$messagePropertyName};
    }

    throw new Exception(sprintf(
        "Missing handler argument mapping for the \"%s\" argument of \"%s::%s\".",
        $argument->getName(),
        $argument->getDeclaringClass()->getName(),
        $argument->getDeclaringFunction()->getName()
    ));
}

We already have the argument as a ReflectionParameter object, so getting the attribute is easy. We’ll fetch the attributes from the argument, which will give us a (possibly empty) list of ReflectionAttribute objects. We’ve not flagged the attribute as repeatable, so we can assume that there can be up to one declaration per argument.

If the list of attributes is not empty, calling newInstance on the first element will give an instance of the attribute with the properties we’ve specified when declaring it on the handler. Otherwise, we’ll just return null.

// inside the WrappingHandlersLocator class:

private function getAttributeForArgument(ReflectionParameter $argument): ?ExtractedValue
{
    $attributes = $argument->getAttributes(ExtractedValue::class);

    if (!count($attributes)) {
        return null;
    }

    return $attributes[0]->newInstance();
}

With what we’ve done so far, whenever the component’s locator finds a handler with a signature that is not suitable by default, we’ll wrap it within a closure that will act as some sort of adapter that will pass the correct arguments to the handler.

If we dispatch the event again, we’ll get the expected result:

$eventBus->dispatch(
    new BookWasPurchased("Example Book", "John Smith", $now)
);

“John Smith bought the “Example Book” book.”

Additionally, when checking the list of messages and handlers, we’ll still get the correct listener:

BookWasPurchased                                                                                           
    handled by PurchaseHistory (when method=recordPurchase)

The whole WrappingHandlersLocator class written up to this point is available here.

Handlers with additional arguments with default values

Now that we have this working, let’s add another argument to the handler that won’t be present in the event, but will have a default value.

class PurchaseHistory
{
    #[Listener(event: BookWasPurchased::class)]
    public function recordPurchase(
        #[ExtractedValue(messageProperty: "title")] string $bookTitle,
        string $customerName,
        int $bookAge = 1
    ): void {
        dd(sprintf(
            "%s bought the \"%s\" book. The book is %d year(s) old.",
            $customerName,
            $bookTitle,
            $bookAge
        ));
    }
}

We’ve made the locator to be throwing exceptions if we try to map an argument that has no matching property with the same name in the message object, or a declared attribute with explicitly specified property name. Because of that, dispatching the event now will result with the following exception:

Missing handler argument mapping for the “bookAge” argument of “PurchaseHistory::recordPurchase”.
^Exception

As the argument has a default value in the handler’s signature, we should be able to pass that value when we cannot retrieve something else from the message.

To achieve that, when no property for a given argument exists in the message object, we’ll check if the argument has a default value specified. If a default value is available, we’ll use that one. Otherwise, we’ll still throw the exception.

// inside the WrappingHandlersLocator class:

private function resolveValueForHandlerArgument(
    ReflectionParameter $argument,
    object $message
): mixed {
    $attribute = $this->getAttributeForArgument($argument);

    $messagePropertyName = $attribute?->messageProperty ?? $argument->getName();

    if (property_exists($message, $messagePropertyName)) { ... }

    if ($argument->isDefaultValueAvailable()) {
        return $argument->getDefaultValue();
    }

    throw new Exception(sprintf(
        "Missing handler argument mapping or default value for the \"%s\" argument of \"%s::%s\".",
        $argument->getName(),
        $argument->getDeclaringClass()->getName(),
        $argument->getDeclaringFunction()->getName()
    ));
}

If we dispatch the event again, we’ll get the new expected result:

“John Smith bought the “Example Book” book. The book is 1 year(s) old.”

The whole WrappingHandlersLocator class written up to this point is available here.

Handlers with additional arguments with no default values

Next, let’s add one more argument to the caller, called $sellerName. However, this time we won’t specify a default value for it.

class PurchaseHistory
{
    #[Listener(event: BookWasPurchased::class)]
    public function recordPurchase(
        #[ExtractedValue(messageProperty: "title")] string $bookTitle,
        string $customerName,
        string $sellerName,
        int $bookAge = 1
    ): void {
        dd(sprintf(
            "%s bought the \"%s\" book. The book is %d year(s) old and was sold by %s.",
            $customerName,
            $bookTitle,
            $bookAge,
            $sellerName
        ));
    }
}

Just as before, as this argument has no mapped property in the message object and no default value, we’ll end up with an exception:

Missing handler argument mapping or default value for the “sellerName” argument of “PurchaseHistory::recordPurchase”.
^Exception

One option that we have here is to leave the code as it is, and just disallow methods with such arguments to be registered as message handlers in our application.

Another option is to add a way to declare a default value for the arguments that will be used only when handling the message, but not when regularly calling the method.

For the second option, we’ll add a new property to the attribute, called defaultValue which will hold the “special” default value.

#[Attribute(Attribute::TARGET_PARAMETER)]
class ExtractedValue
{
    public function __construct(
        public readonly ?string $messageProperty = null,
        public readonly mixed $defaultValue = null
    ) {
    }
}

And we can declare the attribute to the problematic argument:

class PurchaseHistory
{
    #[Listener(event: BookWasPurchased::class)]
    public function recordPurchase(
        // ...
        #[ExtractedValue(defaultValue: "Unknown seller")] string $sellerName,
        // ...
    ): void {
        // ...
    }
}

When resolving the values for such arguments, we’ll check if the attribute declared on it (if present) has a specified default value to be used.

As this property can be specified on attributes applied to properties with default value, it’s up to us to decide which default value we want to have a higher priority when choosing. Here, we’ll just ignore the one specified in the attribute if a default value is specified in the handler’s signature.

As a last resort, we’ll still throw an exception, just as before.

// inside the WrappingHandlersLocator class:

private function resolveValueForHandlerArgument(
    ReflectionParameter $argument,
    object $message
): mixed {
    $attribute = $this->getAttributeForArgument($argument);

    $messagePropertyName = $attribute?->messageProperty ?? $argument->getName();

    if (property_exists($message, $messagePropertyName)) { ... }

    if ($argument->isDefaultValueAvailable()) { ... }

    if ($attribute?->defaultValue) {
        return $attribute->defaultValue;
    }

    throw new Exception(...);
}

Dispatching the event again will give us the expected output:

“John Smith bought the “Example Book” book. The book is 1 year(s) old and was sold by Unknown seller.”

The whole WrappingHandlersLocator class written up to this point is available here.

Handlers with no arguments

As a final example, let’s try what will happen if we register a method with no arguments, as a listener for our event.

class PurchasesCounter
{
    #[Listener(event: BookWasPurchased::class)]
    public function increaseNumber(): void
    {
        dd("Number of purchases increased");
    }
}

If we dispatch the event now, we’ll get the expected output:

“Number of purchases increased”

Also, the list of message and handlers will now show us the both listeners for the event:

BookWasPurchased                                                                                           
    handled by PurchaseHistory (when method=recordPurchase)
    handled by PurchasesCounter (when method=increaseNumber)

Next steps

This is definitely not a complete solution, and most definitely does not cover all the possible cases. It can additionally be adjusted accordingly to the application’s needs.

For example, we can go further and also make it possible for the ExtractedValue attributes to be optionally nested as part of the Listener attribute declared on the method, which is possible since PHP 8.1. That way we can still define everything we need, without bloating the methods’ signatures.

As said before, please use this only as a basis for future experimentation, and make sure you won’t hurt your application’s performance or maintainability by that.

Photo for social media by Ketut Subiyanto.

Using custom PHP attributes for registering and configuring Symfony Messenger handlers

Sun, 09 Jan 2022 11:41:00 +0100

Symfony Messenger provides multiple ways for registration and configuration of message handlers. Nowadays, the handlers are usually registered by implementing the component’s MessageHandlerInterface interface, which makes the handlers auto-configurable by default, or by implementing some interface of ours which we can register for autoconfiguration manually. However, with the addition of the attributes functionality in PHP 8.0, it doesn’t really make sense anymore to use interfaces for the purpose of “describing” our classes. In this article we’ll explore how we can use our own PHP attributes to register and configure the message handlers.

The attributes are more suitable for this purpose as, besides describing the classes, they can also serve as simple data transfer objects that can hold any data we need to pass. Since Symfony 5.4, the Messenger component comes with an #[AsMessageHandler] attribute that serves as a replacement for the mentioned interface, and is great for quickly registering any class as message handler. However, it has a limited set of properties and can be declared only on classes.

If we want to have more flexibility, we can create and use our own attributes. With them, we’ll have bigger control, and we can decouple our classes from the framework. Also, with attributes that can be declared on methods, we can easily define multiple handlers in a same class without the need of additional framework code into it, making it more focused on our business logic.

Let’s begin by saying that whenever a new member joins a community in our application, we’re dispatching an MemberJoinedEvent event:

class MemberJoinedEvent
{
    // ...
}

(I’ll be omitting the namespaces here for simplicity. You can organize the code and place the classes according to your needs.)

The event is being handled by two listeners for taking the following actions:

Start their trial period
Send them a welcome e-mail

And we have the following message bus through which we’re dispatching all the events:

framework:
    messenger:
        buses:
            event_bus: ...

Now we need to register our events’ listeners as services in the Symfony’s container, and tag them as message handlers, so they can be reached by the dispatched events.

Registering the handlers for autoconfiguration

As mentioned above, we’ll create a new attribute with which we’ll mark the listeners as handlers. For now, we can specify the classes as the only target of the attribute. Later in the article we’ll see how we can use the attribute for methods as well.

#[Attribute(Attribute::TARGET_CLASS)]
class Listener
{
}

Next, we’ll declare the attribute on the listener classes:

#[Listener]
final class StartTrialPeriod
{
    public function __invoke(MemberJoinedEvent $event): void { ... }
}

#[Listener]
final class SendWelcomeEmail
{
    public function __invoke(MemberJoinedEvent $event): void { ... }
}

As a final step, we need to tell Messenger that these listener classes are message handlers by tagging each of them with the messenger.message_handler tag.

Similar to the functionality for autoconfiguring services that implement a given interface, since Symfony 5.3 there’s an option to register attributes for autoconfiguration as well.

For that purpose, there’s the registerAttributeForAutoconfiguration method in the ContainerBuilder class, which we’ll use to register the attribute when building the container. As arguments to this method we’ll be passing the classpath of the attribute we want to register, and a configurator - an anonymous function that will be executed for each of the attribute’s declarations (i.e. for each of the listener classes).

As we want our handlers to work on the event_bus message bus, we’ll also set the bus property on the messenger.message_handler tag we’ll be adding to the listener classes.

class Kernel extends BaseKernel
{
    // ...

    protected function build(ContainerBuilder $container): void
    {
        // ...

        $container->registerAttributeForAutoconfiguration(
            Listener::class,
            static function (
                ChildDefinition $definition,
                Listener $attribute,
                ReflectionClass $reflector
            ): void {
                $definition->addTag('messenger.message_handler', [
                    'bus' => 'event_bus'
                ]);
            }
        );
    }
}

We can now use the debug:messenger console command to check the list of messages and handlers:

MemberJoinedEvent
    handled by SendWelcomeEmail
    handled by StartTrialPeriod

With the work we’ve done so far, whenever we declare the #[Listener] attribute on a class, the Messenger component will register that class as a message handler in the event_bus message bus. The new class will also be automatically configured to handle events of the class type-hinted as a first argument in its __invoke method.

Changing the handler method name

Next, let’s try to make it possible to use a different method name (eg. handle) for handling the events, instead of __invoke.

#[Listener]
final class SendWelcomeEmail
{
    public function handle(MemberJoinedEvent $event): void { ... }
}

To specify which method should be called when the event is passed to the handler, we need to set the method property when tagging the handler.

$container->registerAttributeForAutoconfiguration(
    Listener::class,
    static function (
        ...
    ): void {
        $definition->addTag('messenger.message_handler', [
            'bus' => 'event_bus',
            'method' => 'handle'
        ]);
    }
);

However, if we try running this, we’ll get the following error:

Invalid handler service “SendWelcomeEmail”: class “SendWelcomeEmail” must have an “__invoke()” method.
^{500 Internal Server Error - RuntimeException}

At the moment, Messenger will try to resolve the handled message type (in our case the event class) automatically only when the method is not specified explicitly. As a result, in our case, we also need to manually specify the handled event for each of the registered handlers, using the handles property of the tag.

As we will have multiple events, we need to somehow pass the value to the configurator for each of the handlers we want to configure.

For that reason, we’ll add a new property in the attribute:

#[Attribute(Attribute::TARGET_CLASS)]
class Listener
{
    public function __construct(public readonly string $event) { ... }
}

And we’ll provide the value when declaring the attribute on the listener classes:

#[Listener(event: MemberJoinedEvent::class)]
final class SendWelcomeEmail
{
    public function handle(MemberJoinedEvent $event): void { ... }
}

Now, when registering the handlers, in the configurator we’ll read the event property of the attribute instance, and we’ll use that value for the handles property of the tag:

$container->registerAttributeForAutoconfiguration(
    Listener::class,
    static function (
        ChildDefinition $definition,
        Listener $attribute,
        ReflectionClass $reflector
    ): void {
        $definition->addTag('messenger.message_handler', [
            'bus' => 'event_bus',
            'method' => 'handle',
            'handles' => $attribute->event
        ]);
    }
);

If we check the list of messages and handlers now, we’ll see that the listeners will handle the events with the new method name:

MemberJoinedEvent
    handled by SendWelcomeEmail (when method=handle)
    handled by StartTrialPeriod (when method=handle)

Handling multiple messages (events) in the same class

Now that we’re able to use a different method names for the handlers, we can make it more dynamic and also make it possible for us to have multiple methods in the same class that will handle different events. By using the attribute, we’re able to achieve this without implementing any additional interfaces or adding additional methods to our classes.

Let’s say that we have another similar MemberLeftEvent event, and we want to have some service that will keep track of the number of members in a community. In this case, it makes sense to have a class that will contain the listeners for both of the events, which will adjust the number respectively.

As we want the listeners in this case to be represented by the methods, we need to declare the #[Listener] attribute to each of them. First, we’ll make it possible for the attribute to be declared on methods too:

#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
class Listener
{
    ...
}

Next we’ll declare the attributes on each of the methods we want to handle an event:

final class CountMembers
{
    #[Listener(event: MemberJoinedEvent::class)]
    public function increaseNumber(MemberJoinedEvent $event): void { ... }

    #[Listener(event: MemberLeftEvent::class)]
    public function decreaseNumber(MemberLeftEvent $event): void { ... }
}

The third argument in the configurator anonymous function was added in Symfony 5.4, and provides us some reflection info about the place (class, method, property, etc.) where the attribute was declared.

As we’re allowing our attribute to be declared on classes and methods, we’re expecting that argument to be an instance of either ReflectionClass or ReflectionMethod, so we can use an union of these two types when type-hinting the argument.

For the cases where the attribute is declared on a specific method, we’ll fetch the method name from the ReflectionMethod object, and we’ll use it instead of the hardcoded value we had until now. For the cases where the attribute is declared on the class, we’ll fail-back to the handle method as before. If you want to make it more flexible for these cases too, you can add another property to the attribute, which you’ll set when declaring the attribute on the classes.

$container->registerAttributeForAutoconfiguration(
    Listener::class,
    static function (
        ChildDefinition $definition,
        Listener $attribute,
        ReflectionClass | ReflectionMethod $reflector
    ): void {
        $method = ($reflector instanceof ReflectionMethod)
            ? $reflector->getName()
            : 'handle';

        $definition->addTag('messenger.message_handler', [
            'bus' => 'event_bus',
            'method' => $method,
            'handles' => $attribute->event
        ]);
    }
);

If we check the list now, we’ll see both the classes and methods handling the events:

MemberJoinedEvent
    handled by CountMembers (when method=increaseNumber)
    handled by SendWelcomeEmail (when method=handle)
    handled by StartTrialPeriod (when method=handle)

MemberLeftEvent
    handled by CountMembers (when method=decreaseNumber)

Passing additional configuration

As we saw before, we own the attribute class, so we can use them to pass any metadata or configuration options we want.

Now, let’s say that we have two transports - sync for the actions we want to do synchronously, and async for the actions we want to be done asynchronously in the background.

framework:
    messenger:
        # ...

        transports:
             async: '%env(MESSENGER_TRANSPORT_DSN)%'
             sync: 'sync://'

From the handlers, we’d like the SendWelcomeEmail one to be working only in the background, so it’ll handle only events that will come through the async transport.

Instead of specifying the transport inside the listener classes, thus adding more framework code to them, we can add a new boolean property in the attribute which will indicate whether we want the concrete handler to be executed synchronously or asynchronously.

#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD)]
class Listener
{
    public function __construct(
        public readonly string $event,
        public readonly bool $async = false
    ) {
    }
}

And we’ll update the attribute declaration in the listener:

#[Listener(event: MemberJoinedEvent::class, async: true)]
final class SendWelcomeEmail
{
    public function handle(MemberJoinedEvent $event): void { ... }
}

In the configurator for the attribute, we can use the from_transport property of the tag to register the handlers properly:

$container->registerAttributeForAutoconfiguration(
    Listener::class,
    static function (
        ChildDefinition $definition,
        Listener $attribute,
        ReflectionClass | ReflectionMethod $reflector
    ): void {
        $method = ($reflector instanceof ReflectionMethod)
            ? $reflector->getName()
            : 'handle';

        $definition->addTag('messenger.message_handler', [
            'bus' => 'event_bus',
            'method' => $method,
            'handles' => $attribute->event,
            'from_transport' => $attribute->async ? 'async' : 'sync'
        ]);
    }
);

If we check the list now, we’ll see that the welcome e-mail messages will be sent asynchronously, while the rest of the listeners will be executed synchronously:

MemberJoinedEvent
    handled by CountMembers (when method=increaseNumber, from_transport=sync)
    handled by SendWelcomeEmail (when method=handle, from_transport=async)
    handled by StartTrialPeriod (when method=handle, from_transport=sync)

MemberLeftEvent
    handled by CountMembers (when method=decreaseNumber, from_transport=sync)

(Note that in this case the same message is being expected from multiple transports, so it’ll have to be routed to all of them.)

Next steps

If we have other busses for another types of messages in our application, we can create more attribute classes - one for each of them. For example, if we have a command bus too, we can create a #[CommandHandler] attribute. That way, we’ll provide more context, we can specify different configuration options per handler type, and we’ll better distinguish the different types of message handlers.

Photo for social media by Tima Miroshnichenko.

PHP 8 Attributes example: Injecting the current user in Symfony controllers without the security component

Sun, 17 May 2020 23:31:00 +0200

Although we’ve been using annotations in PHP for years, this functionality was not part of the language itself. Instead, we had to rely on parsing the comments formatted as docblocks above the classes, properties or methods, usually with the doctrine/annotations library. With the acceptance of the “Attributes v2” RFC for the next major PHP version, the concept will become part of the PHP core, called “Attributes” and with slightly different syntax: <<Example>> instead of @Example. In this article we’ll see how we can use a custom attribute to tell Symfony how to resolve the currently authenticated user as controller action argument even if we don’t use the security component.

Note: Even though the RFC has been accepted, please consider that at the moment of publishing of this article the functionality is still under development and is not yet merged to the master branch. If you want to try the code presented here now, you will have to compile the PHP source by yourself using the branch from this PR.

The story

Let’s imagine that we’re developing a project that, among others, includes two bounded contexts called “Project Management” and “Authentication”, working as separate applications. Our focus in this article will be on the “Project Management” one that we’re developing as a Symfony application.

As actors in the application we have managers and developers, represented with the Manager and Developer entities respectively (both implementing the EmployeeInterface interface). The managers will be able to create and assign tasks (Task entity) to developers and the developers can mark those tasks as completed. To do their job, both managers and developers are able to authenticate in the system.

The application provides a HTTP API, used by the front-end web interface. To authenticate the employees when we receive a request, we’re passing the Authorization header value to the other “Authentication” application, which then gives us the UUID of the authenticated user. We have those UUIDs assigned the managers and developers in our application, and we can know which manager or developer has sent the request.

As example, here’s the flow for creating a new task:

Resolving the authenticated developer/manager

For assigning the tasks, we have the assignTask controller action in the TasksController, which is mapped to the POST /tasks/{task}/assign/{developer} API endpoint.

In order to perform the task assignment, we need to fetch the task, the developer to which the task will be assigned and the manager who will do the assignment.

For simplicity, we’ll imagine that we use Doctrine ORM and SensioFrameworkExtraBundle, so Symfony will automatically know how to inject the proper task and developer objects in the action, based on the URL. If we don’t want to use that bundle, we can use similar approach as the one discussed later in this article to fetch those objects as well. You may even not need those objects here and just use the IDs.

Here is the general structure of the controller and the action:

class TasksController
{
    /** @Route("/tasks/{task}/assign/{developer}", methods={"POST"}) */
    public function assignTask(
        Request $request,
        Task $task,
        Developer $developer
    ): Response {
        // ...

        return new JsonResponse(/** ... */);
    }
}

The only thing that we miss now is the manager who does the assignment. So, we need to transform the received token from the request to the proper Manager object from the storage. To achieve that, we’ll have the following abstraction:

interface AuthenticatedEmployeeResolverInterface
{
    /** @throws InvalidTokenException */
    public function fromToken(string $token): EmployeeInterface;
}

If the token is invalid, it will throw an InvalidTokenException exception.

As the “Authentication” application will give us only the id of the employee, we’ll also have an EmployeesRepositoryInterface abstraction that will know how to fetch the proper manager or developer from the storage.

interface EmployeesRepositoryInterface
{
    /** @throws EmployeeNotFoundException */
    public function fetchById(string $id): EmployeeInterface;
}

So, in the authenticated employee resolver, first we’ll use a PSR-18 HTTP client in order to exchange the token for the UUID of the user by communicating to the API of the “Authentication” application, and then we’ll fetch the employee from the storage.

class AuthenticatedEmployeeResolver implements AuthenticatedEmployeeResolverInterface
{
    private ClientInterface $httpClient;
    private EmployeesRepositoryInterface $employeesRepository;

    // constructor omitted

    /** @throws InvalidTokenException */
    public function fromToken(string $token): EmployeeInterface
    {
        try {
            $uuid = // send the request and parse the response

            $employee = $this->employeesRepository->findById($uuid);
        } catch (ClientExceptionInterface | EmployeeNotFoundException $exception) {
            throw new InvalidTokenException();
        }
        
        return $employee;
    }
}

Now, let’s first see the approach with injecting the AuthenticatedEmployeeResolverInterface service as constructor argument in the controller, and explicitly using it to fetch the currently authenticated manager when assigning the task.

In the assignTask method, we’ll retrieve the token from the request and then try to resolve the authenticated employee using it. Additionally, we’ll also check if the employee is actually a manager inside our bounded context.

class TasksController
{
    private AuthenticatedEmployeeResolverInterface $employeeResolver;

    // constructor omitted 

    /** @Route("/tasks/{task}/assign/{developer}", methods={"POST"}) */
    public function assignTask(
        Request $request,
        Task $task,
        Developer $developer
    ): Response {
        $token = str_replace(
            'Bearer ',
            '',
            $request->headers->get('Authorization', '')
        );

        try {
            $employee = $this->employeeResolver->fromToken($token);
        } catch (InvalidTokenException $exception) {
            return $this->createUnauthorizedResponse();
        }

        if (!$employee instanceof Manager) {
            return $this->createUnauthorizedResponse();
        }

        // ... do the assignment by sending a command or something similar

        return new JsonResponse(/** ... */);
    }

    private function createUnauthorizedResponse(): Response
    {
        return new JsonResponse('Unauthorized', Response::HTTP_UNAUTHORIZED);
    }
}

With this, we’ve managed to fetch the proper manager and now we can use it to do the task assignment. However, this bloats our controllers, as we need to inject the AuthenticatedEmployeeResolverInterface abstraction and parse the token in all controllers in which we need the authenticated employee.

Luckily, Symfony provides a mechanism called “Action Argument Resolving” which will help us replace the whole authentication related code from the controllers with a single PHP attribute.

As we can see in the Symfony documentation, there’s an existing UserValueResolver resolver, but using it will require us to install the whole Symfony Security component and make our Manager and Developer entities implement the component’s UserInterface which is too much for our case.

So, we need to extend the argument resolving mechanism by creating a new argument value resolver which will implement the Symfony\Component\HttpKernel\Controller\ArgumentValueResolverInterface interface.

Even though both types of employees implement the EmployeeInterface we can’t just make it resolve any argument implementing this interface, or each of the entity classes separately, because as we saw, we can have controller action methods that require multiple such objects, of which only one is the authenticated and the others should be fetched from the storage. That’s why we need to mark the authenticated one with an attribute.

Our final result will look like this:

class TasksController
{
    /** @Route("/tasks/{task}/assign/{developer}", methods={"POST"}) */
    public function assignTask(
        <<Authenticated>> Manager $manager,
        Task $task,
        Developer $developer
    ): Response {

        // ... send a command to the command bus or something similar

        return new JsonResponse(/** ... */);
    }
}

So, we’ll create a custom PHP attribute called Authenticated. To do that, as defined in the RFC, we need to create a class with that name and add a PhpAttribute attribute on it. Note that the PHP’s PhpAttribute class is in the global space, so you will probably have to import it or use it as \PhpAttribute.

<<PhpAttribute>>
class Authenticated
{
}

As defined in the interface, the argument value resolver will have two methods. One (supports) that receives the request and an attribute metadata and tells Symfony whether this resolver should be used for the specific attribute. When doing the resolving, Symfony goes through all the registered resolvers for each of the controller action attributes and by calling this methods checks which resolvers should it use. The other one (resolve) is the one that will actually provide the proper value that should be passed to the controller action method.

Let’s see each of the two methods separately.

class AuthenticatedEmployeeArgumentValueResolver implements ArgumentValueResolverInterface
{
    // constructor and properties omitted, but will be needed later

    public function supports(Request $request, ArgumentMetadata $argument): bool
    {
        $controller = $request->attributes->get('_controller');
        [$className, $methodName] = explode("::", $controller);

        $parameter = new ReflectionParameter(
            [$className, $methodName],
            $argument->getName()
        );

        $attributes = $parameter->getAttributes();

        return in_array(
            Authenticated::class,
            array_map(
                fn(ReflectionAttribute $attribute): string => $attribute->getName(), 
                $attributes
            )
        );
    }
    
    public function resolve(Request $request, ArgumentMetadata $argument): iterable { ... }
}

The controller resolving happens before the argument resolving, so we can take that information from the request’s attributes. With it, we can find out the needed controller class and action method. Note that the code above can be slightly changed if we were using invokable controller classes as actions, but the main logic is still same. Having that information, we can now use the reflection API to get more information about the method’s argument/property.

As defined in the RFC, the reflection classes that represent classes, functions, properties and class constants now come with a new getAttributes method which returns an array of ReflectionAttribute objects. We’ll use that method on our ReflectionParameter object that represents the current argument to retrieve all attributes placed on it.

Then we can use the getName method for each of the found attributes to find out their FQCNs and check if any of it matches the custom attribute that we created.

If our attribute is matched in the list of attributes for the argument, the next method from our value resolver is called - the resolve one.

class AuthenticatedEmployeeArgumentValueResolver implements ArgumentValueResolverInterface
{
    private AuthenticatedEmployeeResolverInterface $employeeResolver;

    // constructor omitted

    public function supports(Request $request, ArgumentMetadata $argument): bool { ... }

    public function resolve(Request $request, ArgumentMetadata $argument): iterable
    {
        $token = str_replace(
            'Bearer ',
            '',
            $request->headers->get('Authorization', '')
        );

        try {
            $employee = $this->employeeResolver->fromToken($token);
        } catch (InvalidTokenException $exception) {
            throw new UnauthenticatedException();
        }

        $argumentType = $argument->getType();

        if (!$employee instanceof $argumentType) {
            throw new UnauthorizedException();
        }

        yield $employee;
    }
}

We can see that the logic in the resolve method is almost identical to what we previously had in the controller. One of the differences here is that we don’t just create a HTTP response in the invalid cases, but throw custom exceptions instead. Later, we’ll tell Symfony how to convert those exceptions to proper HTTP responses.

Another difference is that we don’t explicitly check if the employee is of a specific type. We do that in a more flexible way, by getting the argument type from the argument metadata. That allows us to specify the employee type as a type hint in the controller action, making all of the following cases supported:

class EmployeesController
{
    /** @Route("/profile", methods={"GET"}) */
    public function profile(
        <<Authenticated>> EmployeeInterface $employee
    ): Response {
        // Any type of employee is allowed to access this route
    }
}

class TasksController
{
    /** @Route("/tasks/{task}/assign/{developer}", methods={"POST"}) */
    public function assignTask(
       <<Authenticated>> Manager $manager
        Task $task,
        Developer $developer
    ): Response {
        // This is allowed only for managers
    }

    /** @Route("/tasks/{task}/complete", methods={"POST"}) */
    public function completeTask(
           <<Authenticated>> Developer $developer,
            Task $task
        ): Response {
        // This is allowed only for developers
    }
}

As a final step, we just have to let Symfony know how to transform the UnauthenticatedException and UnauthorizedException exceptions to a HTTP response. Here’s just a simple example how this can be done:

class ExceptionsSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [KernelEvents::EXCEPTION => 'handleException'];
    }

    public function handleException(ExceptionEvent $event)
    {
        $statusCodes = [
            UnauthenticatedException::class => Response::HTTP_UNAUTHORIZED,
            UnauthorizedException::class => Response::HTTP_FORBIDDEN
        ];

        $exceptionClass = get_class($event->getThrowable());

        if (!isset($statusCodes[$exceptionClass])) {
            return;
        }

        $event->setResponse(
            new JsonResponse(/* ... */, $statusCodes[$exceptionClass])
        );
    }
}

Conclusion

Annotations are widely used in other popular languages (such as Java) and having them now in the PHP core (as attributes) opens many new possibilities. As previously noted, the feature is accepted for PHP 8 and although it is working for the cases discussed here, it is still under development. The releasing of PHP 8 is currently scheduled for December 2020, more than half a year from now, a long period in which many things may happen or change. However, I believe that the general ideas discussed here will remain applicable.

Also, since PHP 8 is still in development, many of the libraries (including Doctrine) may not work with it at this moment, so making all the code presented here work requires switching between versions and doing some improvisations. Please do not focus too much on the details, as the important thing here is to understand the general idea.

Decomposing the user checking mechanism in Symfony

Thu, 02 Aug 2018 12:07:00 +0200

The user checkers in the Symfony Security component allow us to control whether an user can be authenticated in our system, even if they have entered their correct credentials. In this article we’ll see how we can make the process more flexible by splitting our checking logic from one to multiple checkers.

As written in the documentation, we can set a custom user checker for each of the firewalls we have in our security configuration:

security:
    firewalls:
        main:
            pattern: ^/
            user_checker: App\Security\UserChecker

Let’s imagine that we are developing an application that has the following requirements for the users in order for them to be allowed to login into the system:

The user has an approved account
The user is not banned
The user has a valid subscription

Using a general User Checker

As the configuration allows us to configure only one service as user checker per firewall, it may seem convenient for us to put all those checks in a single user checker class:

class UserChecker implements UserCheckerInterface
{
    private $bansChecker;
    private $subscriptionValidator;

    public function __construct(
        UserBansChecker $bansChecker,
        SubscriptionValidator $subscriptionValidator
    ) {
        $this->bansChecker = $bansChecker;
        $this->subscriptionValidator = $subscriptionValidator;
    }

    public function checkPreAuth(UserInterface $user) : void
    {
        if (!$user->isApproved()) {
            throw new UserNotApprovedAuthenticationException();
        }
    }

    public function checkPostAuth(UserInterface $user) : void
    {
        if ($this->bansChecker->isBanned($user)) {
            throw new UserBannedAuthenticationException();
        }

        if ($this->subscriptionValidator->hasValidSubscription($user)) {
            throw new SubscriptionExpiredAuthenticationException($user);
        }
    }
}

If we’re working with a bigger and more complex application, the logic of the checkers may be distributed along multiple modules in the system. Although it’s simple, in the example above we can see that the rules for the checking can come from different modules like “Subscriptions”, “Users”, “User Banning”, etc.

Each of those modules may have its own business logic, and having this one user checker, we’re moving pieces of that logic to a single place, perhaps in some “Authentication” module.

We already know that business requirements always change, so we can certainly be sure that the business logic we’re working with in our application will have to change as well.

Let’s imagine that we’ve stopped to support our services in some countries, so we’ll have to disallow the users from those countries to login into the application. In such case we’ll have to modify our existing class, clearly violating the “Open–closed principle”. Besides having to modify our checker class, we’ll also have to modify our tests for this class, to mock more services there and possibly to make the existing cases more complicated. And the same applies for removing a check too.

For most of the rules included in the checker, we’ll have to inject some service. As we’ll be adding more and more rules, this list will grow too, making the checker depending on more and more services.

Decomposing the checking logic

Instead of having all the checks combined in a single class, we can split them and define the following three checkers:

class UserApprovalStatusUserChecker implements UserCheckerInterface
{
    public function checkPreAuth(UserInterface $user)
    {
        if (!$user->isApproved()) {
            throw new UserNotApprovedAuthenticationException();
        }
    }

    public function checkPostAuth(UserInterface $user)
    {
    }
}

class BannedUsersUserChecker implements UserCheckerInterface
{
    private $bansChecker;

    public function __construct(UserBansChecker $bansChecker)
    {
        $this->bansChecker = $bansChecker;
    }

    public function checkPreAuth(UserInterface $user): void
    {
    }

    public function checkPostAuth(UserInterface $user): void
    {
        if ($this->bansChecker->isBanned($user)) {
            throw new UserBannedAuthenticationException();
        }
    }
}

class SubscriptionUserChecker implements UserCheckerInterface
{
    private $subscriptionValidator;

    public function __construct(SubscriptionValidator $subscriptionValidator)
    {
        $this->subscriptionValidator = $subscriptionValidator;
    }

    public function checkPreAuth(UserInterface $user)
    {
    }

    public function checkPostAuth(UserInterface $user)
    {
        if ($this->subscriptionValidator->hasValidSubscription($user)) {
            throw new SubscriptionExpiredAuthenticationException($user);
        }
    }
}

Having them separated, we can organize the classes better by moving them to the proper modules they belong to.

Each of the checkers can now be tested separately, leading to cleaner, simpler and more maintainable tests.

Let’s go back to the case when we need to add an additional user checker. To achieve the same, now we only have to write the new user checker class, without touching the existing ones. As the new class can be tested separately, the unit tests for the other checkers can remain untouched as well.

Removing an user checker now is just a matter of removing the checker class.

As the checkers are now defined per module instead of a central place, we can easily extend the checking process by adding new modules which will have their own checkers defined.

Wiring the checkers together

We remember that the configuration of the Symfony Security component allows us to define only one user checker per firewall. As we now have more than one checker, we’ll create a composite user checker which will hold the other checkers and call them when needed. We’ll register that checker as a service and configure it as checker for our firewall.

class CompositeUserChecker implements UserCheckerInterface
{
    /** @var UserCheckerInterface[] */
    private $checkers = [];

    public function addChecker(UserCheckerInterface $userChecker)
    {
        $this->checkers[] = $userChecker;
    }

    public function checkPreAuth(UserInterface $user)
    {
        foreach ($this->checkers as $checker) {
            $checker->checkPreAuth($user);
        }
    }

    public function checkPostAuth(UserInterface $user)
    {
        foreach ($this->checkers as $checker) {
            $checker->checkPostAuth($user);
        }
    }
}

security:
    firewalls:
        main:
            pattern: ^/
            user_checker: Acme\Core\Security\CompositeUserChecker

The next thing we need is the mechanism of adding our checkers to the composite one.

We’ll register all the checkers as services and tag them with a user_checker tag.

services:

    Acme\Users\Authentication\UserApprovalStatusUserChecker:
        tags: ['user_checker']

    Acme\Users\Banning\Authentication\BannedUsersUserChecker:
        tags: ['user_checker']

    Acme\Subscriptions\Authentication\SubscriptionUserChecker:
        tags: ['user_checker']

Alternatively, since all of our checkers implement the Symfony\Component\Security\Core\User\UserCheckerInterface interface, instead of manually adding the tags, we can register the interface for autoconfiguration in our Kernel.

class Kernel extends BaseKernel
{
    // ...

    protected function build(ContainerBuilder $container)
    {
        $container
            ->registerForAutoconfiguration(UserCheckerInterface::class)
            ->addTag('user_checker');
    }
}

We now have our checkers registered and configured. The final step is to add them to the composite checker. To do that, we’ll have a compiler pass that will find the tagged checkers when compiling the container, and add them to the composite checker:

class UserCheckersCompilerPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container)
    {
        $mainChecker = $container->findDefinition(CompositeUserChecker::class);

        $userCheckers = $container->findTaggedServiceIds('user_checker');

        foreach ($userCheckers as $checker => $tags) {
            if ($checker === $mainChecker->getClass()) {
                continue;
            }

            $mainChecker->addMethodCall('addChecker', [new Reference($checker)]);
        }
    }
}

Further ideas

In bigger and more complex applications, it is very likely that we’ll have multiple firewall with different authentication requirements.

As the checks for all the requirements are now represented as separate classes, we can easily combine any of them in multiple instances of the composite checker and use them for the proper fiewalls.

As a final note, I would like to note that even though we’ve made the checking process more flexible, we’re still coupling part of our business logic to the Symfony Security component. Let’s have that topic for a possible future article :)

Using the Go! Aspect-Oriented Framework to trim values before validation

Sun, 17 Sep 2017 14:15:00 +0200

Few weeks ago, while using the NotBlank constraint from the Symfony Validator to validate a command before executing it, a co-worker of mine noticed that the values are not automatically trimmed, so it would allow strings of empty spaces to be passed as valid values.

We were already using the Symfony Forms component with the command classes set for the data_class property in the forms, and the trimming was done there by default. As the commands can be initialized from another places in the applications as well, this is not enough and we must be sure that the data is still properly validated.

While looking for multiple approaches how this can be solved, it came to my mind that this is a case where we can finally give Aspect-Oriented Programming a try.

My first contact with the AOP paradigm was few years ago while exploring the Spring framework in Java. My impression was that the AOP way of connecting things is too messy and can easily lead us to having a big mess in our applications, so I didn’t dig much deeper into the approach.

However, after listening to Alexander Lisachenko’s “Solving Cross-Cutting Concerns in PHP” talk at the PHP Serbia Conference this spring, although still suspicous about relying too much on the concept, I was kind of convinced that AOP can be useful for some simpler tasks in our applications.

The Go! Aspect-Oriented Framework is a popular AOP framework in the PHP ecosystem (and probably the only one I had heard of before), so I chose it for the experiment.

Let’s imagine that we want to validate the values passed in a PostCommentCommand command before executing it.

use Symfony\Component\Validator\Constraints as Assert;

class PostCommentCommand
{
    /** @Assert\NotBlank() */
    private $author;

    /** @Assert\NotBlank() */
    private $content;

    public function __construct(string $author, string $content)
    {
        $this->author = $author;
        $this->content = $content;
        // other stuff if needed...
    }

    // getters...
}

If we create an instance of the command and pass strings of empty spaces as values for the $author and $content arguments, we can see that no constraints are violated.

use Symfony\Component\Validator\Validation;

$validator = Validation::createValidatorBuilder()
    ->enableAnnotationMapping()
    ->getValidator();

$command = new PostCommentCommand('  ', '  ');

$violations = $validator->validate($command);

dump($violations);

ConstraintViolationList {#20 ▼
  -violations: []
}

When using the Go! AOP framework, in order to trim the values of the constructor arguments before validating them, we need to create an Aspect class where the actual trimming would take place.

Aspect: A modularization of a concern that cuts across multiple objects. Logging, caching, transaction management are good examples of a crosscutting concern in PHP applications. Go! defines aspects as regular classes implemented empty Aspect interface and annotated with the @Aspect annotation.

In the aspect class, we’ll have an method that we’d like to be called whenever we call a method whose string arguments need to be trimmed. When called, this method will receive an instance of the MethodInvocation class that will contain details about the originally called method, including a list of the values given as arguments in the call. We can then take the string arguments from the list and trim their values.

use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;

class TrimStringValuesAspect implements Aspect
{
    public function trimStringArgumentValues(MethodInvocation $invocation)
    {
        $invocation->setArguments(array_map(function($argument) {
            return is_string($argument) ? trim($argument) : $argument;
        }, $invocation->getArguments()));
    }
}

The Go! framework needs to know when it should call the method we just created. To tell it, we should define the method as an Advice and give it a properly defined way to match join points.

Advice: Action taken by an aspect at a particular join point. There are different types of advice: @Around, @Before and @After advice.

In our concrete example, we need to call the aspect before the constructor of the command class is called, so we’ll use the @Before advice annotation.

Before advice: Advice that executes before a join point, but which does not have the ability to prevent execution flow proceeding to the join point (unless it throws an exception).

The join points matchers are defined using a concept called Pointcuts.

Pointcut: A regular expression that matches join points. Advice is associated with a pointcut expression and runs at any join point matched by the pointcut (for example, the execution of a method with a certain name).

The first way for defining a pointcut we’ll take a look at is to use a regular expression to define a pattern that will be used to check if the given advice should be called when a method in another place is being executed.

We would like the trimStringArgumentValues() method of our TrimStringValuesAspect class to be called before an instance of our command classes (all classes whose name ends with the word Command) is created, so we’ll have the following advice definition:

/**
 * @Before("execution(public **\*Command->__construct(*))")
 */
public function trimStringArgumentValues(MethodInvocation $invocation){ ... }

Another thing we need to do is to register the aspect in the framework. We’ll see how we can do that bellow in this article.

Having the aspect defined, if we validate the created command object again, we get the two expected violations:

ConstraintViolationList {#284 ▼
  -violations: array:2 [▼
    0 => ConstraintViolation {#305 ▼
      -message: "This value should not be blank."
      -root: PostCommentCommand {#279 ▶}
      -propertyPath: "author"
      -invalidValue: ""
      -constraint: NotBlank {#291 ▶}
      // ...
    }
    1 => ConstraintViolation {#306 ▼
      -message: "This value should not be blank."
      -root: PostCommentCommand {#279 ▶}
      -propertyPath: "content"
      -invalidValue: ""
      -constraint: NotBlank {#300 ▶}
      // ...
    }
  ]
}

Another way for defining when the advice should be called is to use an annotation pointcut. Defining it this way, it will allow the trimStringArgumentValues() method to be called before execution of any method in any class annotated with a custom annotation we’d create.

We’ll create a new annotation class called, for example, TrimmableArgumentValues:

use Doctrine\Common\Annotations\Annotation;

/**
 * @Annotation
 * @Target("METHOD")
 */
class TrimmableArgumentValues extends Annotation
{
}

We’d now change the definition of the advice in our aspect to match only the methods annotated with our annotation:

/**
 * @Before("@execution(Acme\TrimmableArgumentValues)")
 */
public function trimStringArgumentValues(MethodInvocation $invocation) { ... }

The constructor method of our command class will not be automatically associated with the aspect anymore, so we’ll annotate it with the TrimmableArgumentValues annotation:

class PostCommentCommand
{
    // ...

    /**
     * @TrimmableArgumentValues
     */
    public function __construct(string $author, string $content)
    {
        $this->author = $author;
        $this->content = $content;
        // other stuff if needed...
    }

    // ...
}

If we validate the command object again, we’ll still get the same expected violations.

Integrating the Go! AOP framework into our applications is well described in the framework’s documentation.

We should create a new kernel class that would extends the Go\Core\AspectKernel class. In this kernel we’ll register our aspects.

use Go\Core\AspectContainer;
use Go\Core\AspectKernel;

class ApplicationAspectKernel extends AspectKernel
{
    protected function configureAop(AspectContainer $container)
    {
        $container->registerAspect(new TrimStringValuesAspect());
    }
}

Then, in our front controller (or some other proper place in the application) we’ll initialize and configure the kernel:

$applicationAspectKernel = ApplicationAspectKernel::getInstance();
$applicationAspectKernel->init([
    'debug' => true,
    'cacheDir'  => __DIR__ . '/cache',
    'includePaths' => [
        __DIR__ . '/src/'
    ]
]);

If we want to use it withing the Symfony Framework, we can use the official GoAopBundle bundle.

Having this bundle installed, we only need to register our aspects as a services and tag them with a goaop.aspect tag:

services:
    Acme\TrimStringValuesAspect:
        tags:
            - { name: goaop.aspect }

As I said before, this is a first time I’m giving the AOP approach a try, so I can’t guarantee if this way of dealing with the argument values is actually good on a long term basis.

If you want to share any opinions, ping me on Twitter.

On creating cleaner and simpler commands

Mon, 21 Aug 2017 11:10:00 +0200

Commands, as part of the CQRS pattern, provide a clean way for representing intentions for changing some state in our application. We’ve been working with CQRS for some time and it helped us significantly improve the quality of our code base. Meanwhile, we learned a lot, but we also made some mistakes. In this article we’ll discuss some of the mistakes we were making when using commands and what we did to improve them.

Imagine that, for example, we want to promote an employee to another position. We would have something like the following:

class PromoteEmployeeCommand
{
    private $employeeId;
    private $position;

    public function __construct(string $employeeId, string $position)
    {
        $this->employeeId = $employeeId;
        $this->position = $position;
    }

    public function getEmployeeId() : string
    {
        return $this->employeeId;
    }

    public function getPosition() : string
    {
        return $this->position;
    }
}

Instead of handling the business logic needed for changing an employee’s position inside a controller, we can now call this command, making our application independent of the HTTP layer. At same time, we let the controller serve their right purpose – transforming the received data and sending it to the application’s model layer.

Taking the needed actions to actually promote the employee will be handled in a separate “handler” class:

class PromoteEmployeeCommandHandler
{
    public function handle(PromoteEmployeeCommand $command) : void
    {
        // ...
    }
}

If you’re not already familiar with the concept, you can read about CQRS, different types of messages for communication within the application and more in this article by Matthias Noback.

However, there are cases when, if we don’t model our commands properly, we can introduce mess and confusion into our application and even make it hard to scale and debug.

Such case is when we need to have commands for creating new resources. In that case, the amount of data we receive with the request may contain a long list of properties and values. In this article we’ll discuss some techniques for creating simpler and cleaner commands for this type of cases.

Let’s imagine that we need to employ a new person in our company. Every employee would have first name, last name, email address, phone number, position and salary.

Avoiding data arrays as only argument for new commands

Knowing that our HTTP library can easily provide us the needed data as an array extracted from the request, it may be tempting for us to make our command receive that array and let the appropriate handler deal with it:

class EmployNewPersonCommand
{
    private $data;

    public function __construct(array $data)
    {
        $this->data = $data;
    }

    public function getData() : array
    {
        return $this->data;
    }
}

To create a new instance of this command, we just ask the request for the data and then pass the same array to the command:

public function employAction(Request $request)
{
    $employeeData = $request->request->all();

    $command = new EmployNewPersonCommand($employeeData);
    // ...
}

Modeling the commands this way may seem really clean, allowing us to more rapidly create and execute new commands. However, as our application grows, this can become really messy and can cause a lot of confusion.

One of the main problems here is that, whenever we need to create a new instance of the command, there is no information about what should be put inside the expected array of data. And don’t forget that the purpose of the commands is not to be called just from one point in our application (eg. only one controller method).

With this problem, when somebody needs to create a new instance of the command, instead of just telling what they need to be done, they must find the appropriate handler for the needed command, dig inside it and determine what are the proper keys of the array and what should be put inside them.

Even then, some of the keys may be mistaken or missed, so we are given a possibility to create commands with incomplete or invalid data.

To ensure all the required information is passed to the command when it is created, we need to do some key existence checking in the commands’ constructors, or even worse, in their handlers.

We can avoid such problems by making sure we always list all required information as separate arguments with proper types in the commands’ constructors, making the commands impossible to instantiate if something is missing:

class EmployNewPersonCommand
{
    private $firstName;
    private $lastName;
    private $emailAddress;
    private $phoneNumber;
    private $position;
    private $salary;

    public function __construct(
        string $firstName,
        string $lastName,
        string $emailAddress,
        string $phoneNumber, 
        string $position, 
        float $salary
    ) {
        $this->firstName = $firstName;
        $this->lastName = $lastName;
        $this->emailAddress = $emailAddress;
        $this->phoneNumber = $phoneNumber;
        $this->position = $position;
        $this->salary = $salary;
    }

    public function getFirstName() : string
    {
        return $this->firstName;
    }
    
    public function getLastName() : string
    {
        return $this->lastName;
    }

    // other getters
}

Using value objects for cleaner command arguments

You probably notice another problem in our command’s current design – it became bloated with long list of properties and getter methods.

We should also validate the information inside all of those properties, so our command can become even bigger and more messy.

To make our command simpler, we can create multiple value objects in which we can group and organize the values, and use them as arguments for our command.

For example, we can group the first and last name in a PersonalDetails value object. The email address and phone number would get a separate EmailAddress and PhoneNumber value objects. For the position and the salary we can create the Employment class. Note that this is just an example of how the information can be organized and you should think of your domain logic when creating the classes.

Each of the value object can be validated independently, which gives us even better separation.

With this reorganization, our command now expects three defined arguments:

class EmployPersonCommand
{
    private $personalDetails;
    private $contacts;
    private $employment;

    public function __construct(PersonalDetails $personalDetails, array $contacts, Employment $employment)
    {
        $this->personalDetails = $personalDetails;
        $this->contacts = $contacts;
        $this->employment = $employment;
    }

    public function getPersonalDetails() : PersonalDetails
    {
        return $this->personalDetails;
    }

    public function getContacts() : array
    {
        return $this->contacts;
    }

    public function getEmployment() : Employment
    {
        return $this->employment;
    }
}

To create a new instance, firstly we need to prepare the value objects and then give them to the command:

$personalDetails = new PersonalDetails(
    $request->get('firstName'), 
    $request->get('lastName')
);

$email = new EmailAddress($request->get('email'));
$phoneNumber = new PhoneNumber($request->get('phoneNumber'));

$employment = new Employment(
    $request->get('position'), 
    $request->get('salary')
);
        
$command = new EmployPersonCommand(
    $personalDetails, 
    [$email, $phoneNumber], 
    $employment
);

We can reuse the same value objects in multiple places in our application, for example to make the entities or form types cleaner as well.

Using multiple commands instead of just one

If the domain logic we’re working on allows us, we can improve the command to have less responsibilities and to cause less implications by separating it into multiple smaller commands.

Currently, our command receives multiple types of information about our new employee – their personal details, contact details and details about the new employment.

If we need a possibility to add more contact details to an existing employee in future, we would create a new command for that purpose, possibly causing us to duplicate some existing code. If our domain logic allows for an employee to exist without providing us contact details, we can extract this into separate command which we can later use in another use case.

We may even be able to firstly store the person’s personal details before we employ them, allowing us to store details about persons related to us in a different ways (eg. interns).

So, instead of taking all this action by calling a single command, we can have the following three commands, which we can call from multiple places and in multiple cases:

class CreatePersonCommand { ... }

class EmployPersonCommand { ... }

class AddContactDetailsForEmployee { ... }

And to call them one by one:

public function employAction(Request $request)
{
    // ...

    $this->handle(new CreatePersonCommand(...));
    $this->handle(new EmployPersonCommand(...));
    $this->handle(new AddContactDetailsForEmployee(...));
}

Note that, since the commands are not supposed to be returning anything, in order to know the identity of the created person who we want to employ, we should generate their ID before the commands are called. Another thing we need to be careful is that these commands should be called synchronically, because we must be sure that the person we want to employ already exists in our application.

public function employAction(Request $request)
{
    // ...

    $id = $this->uuids->generate();

    $this->handle(new CreatePersonCommand($id, ...));
    $this->handle(new EmployPersonCommand($id, ...));
    $this->handle(new AddContactDetailsForEmployee($id, ...));
}

As you’ve read here in this article there are some ways to improve our commands’ design. You should always be aware of the requirements of the domain of your application before taking such decisions.

In general, always try to make your commands concise, simpler and reusable.

Note: This article was originally published on my employer's web site. You can also read it here. Any republishing of the article as a whole or in parts should be done in compliance with that site's content licensing.

Symfony3 Form Component and type hinting in PHP 7.0

Wed, 01 Jun 2016 02:15:37 +0200

Type hinting the methods’ arguments and declaring their return types is one of the best improvements that came with PHP 7. When I finally got a chance to play with it in an experimental side project using Symfony, I got stuck trying to combine the type hinting and the Symfony3 Form component.

This post is an explaination of what happened in my case and what I did to make it work. It may not be the best solution and I still haven’t tried to use this with a form that includes some more complex types (eg. EntityType).

Lets begin with a list of the two problems that occured:

Trying to access a property with a null value, using a setter declared to return strings.
Trying to pass a null value to a setter expecting a string.

For a better elaboration of the problems, let’s imagine that we have a system for articles that only contain titles. Here’s the simple entity class:

namespace AppBundle\Entity;

use Symfony\Component\Validator\Constraints as Assert;

class Article
{
    /**
     * @Assert\NotBlank(message="Each article must have a title.")
     */
    private $title;

    public function getTitle() : string
    {
        return $this->title;
    }

    public function setTitle(string $title)
    {
        $this->title = $title;
    }
}

And the custom form field type for the created entity:

namespace AppBundle\Form\Type;

use AppBundle\Entity\Article;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

class ArticleType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder->add('title', TextType::class);
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefault('data_class', Article::class);
    }
}

The first said problem occurs when we want to create the form and we provide the form factory an object of the entity class to read the default data from. The service then tries to read the properties of the object using its getter methods. If any of the properties has a null value, instead of a value whose type corresponds to the return type of the getter, and we don’t have any logic in the getter (we just return the property’s value as it is, like in the example above), we’d get an exception similar to the following one:

Type error: Return value of AppBundle\Entity\Article::getTitle() must be of the type string, null returned
^{500 Internal Server Error - FatalThrowableError}

To fix the problem in our example, we should set the default value of the $title property to be an empty string:

class Article
{
    ...
    private $title = "";
    ...
}

With what we’ve done by now, we fixed the first problem and we’re getting the form rendered in our browser.

However, if we try to submit the form while leaving the “title” field empty, instead of having the validation component arguing about the field being blank (as we specified in the entity class), we’ll get the following exception:

Expected argument of type “string”, “NULL” given
^{500 Internal Server Error - InvalidArgumentException}

This is the second said problem, happening when the service tries to fill the object with the data submitted from the form. It will try to use the setTitle(string $title) method to set the value from the “title” field. Since we didn’t fill anything in the field, it will try to pass null as a value to the setter that expects a string, so the system will throw the exception.

So, to solve the problem, we should have something to convert the value from null to an empty string before it’s passed to the setter in the object.

When I looked for a solution around the web, the Stack Overflow user HPierce suggested that I can use a data transformer to fix the submitted data.

namespace AppBundle\Form\DataTransformer;

use Symfony\Component\Form\DataTransformerInterface;

class NullToEmptyStringDataTransformer implements DataTransformerInterface
{
    public function transform($value)
    {
        return $value;
    }

    public function reverseTransform($value)
    {
        return (is_null($value)) ? (string) $value : $value;
    }
}

As a final step, we should add the data transformer to the field in the method where we’re building the form (in the ArticleType class):

public function buildForm(FormBuilderInterface $builder, array $options)
{
    ...

    $transformer = new NullToEmptyStringDataTransformer();
    $builder->get('title')->addModelTransformer($transformer);
}

If we now try to submit the form without any value in the “title” field, the data will be processed and we should get the specified validation error message.

If you have a comment or a better solution, please ping me on Twitter.