Scheduler

Cron Expression Triggers

Before using cron triggers, you have to install the following dependency:

1

$ composer require dragonmantank/cron-expression

Then, define the trigger date/time using the same syntax as the cron command-line utility:

1
2
3
4

RecurringMessage::cron('* * * * *', new Message());

// optionally you can define the timezone used by the cron expression
RecurringMessage::cron('* * * * *', new Message(), new \DateTimeZone('Africa/Malabo'));

You can also use some special values that represent common cron expressions:

• @yearly, @annually - Run once a year, midnight, Jan. 1 - 0 0 1 1 *
• @monthly - Run once a month, midnight, first of month - 0 0 1 * *
• @weekly - Run once a week, midnight on Sun - 0 0 * * 0
• @daily, @midnight - Run once a day, midnight - 0 0 * * *
• @hourly - Run once an hour, first minute - 0 * * * *

For example:

1

RecurringMessage::cron('@daily', new Message());

1

RecurringMessage::cron('#midnight', new Message());

Periodical Triggers

These triggers allows to configure the frequency using different data types (string, integer, DateInterval). They also support the relative formats defined by PHP datetime functions:

1
2
3
4
5
6
7

RecurringMessage::every('10 seconds', new Message());
RecurringMessage::every('3 weeks', new Message());
RecurringMessage::every('first Monday of next month', new Message());

$from = new \DateTimeImmutable('13:47', new \DateTimeZone('Europe/Paris'));
$until = '2023-06-12';
RecurringMessage::every('first Monday of next month', new Message(), $from, $until);

Custom Triggers

Custom triggers allow to configure any frequency dynamically. They are created as services that implement TriggerInterface.

For example, if you want to send customer reports daily except for holiday periods:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// src/Scheduler/Trigger/NewUserWelcomeEmailHandler.php
namespace App\Scheduler\Trigger;

class ExcludeHolidaysTrigger implements TriggerInterface
{
    public function __construct(private TriggerInterface $inner)
    {
    }

    // use this method to give a nice displayable name to
    // identify your trigger (it eases debugging)
    public function __toString(): string
    {
        return $this->inner.' (except holidays)';
    }

    public function getNextRunDate(\DateTimeImmutable $run): ?\DateTimeImmutable
    {
        if (!$nextRun = $this->inner->getNextRunDate($run)) {
            return null;
        }

        // loop until you get the next run date that is not a holiday
        while ($this->isHoliday($nextRun)) {
            $nextRun = $this->inner->getNextRunDate($nextRun);
        }

        return $nextRun;
    }

    private function isHoliday(\DateTimeImmutable $timestamp): bool
    {
        // add some logic to determine if the given $timestamp is a holiday
        // return true if holiday, false otherwise
    }
}

Then, define your recurring message:

1
2
3
4
5
6

RecurringMessage::trigger(
    new ExcludeHolidaysTrigger(
        CronExpressionTrigger::fromSpec('@daily'),
    ),
    new SendDailySalesReports('...'),
);

Finally, the recurring messages has to be attached to a schedule:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// src/Scheduler/SaleTaskProvider.php
namespace App\Scheduler;

#[AsSchedule('uptoyou')]
class SaleTaskProvider implements ScheduleProviderInterface
{
    public function getSchedule(): Schedule
    {
        return $this->schedule ??= (new Schedule())
            ->with(
                RecurringMessage::trigger(
                    new ExcludeHolidaysTrigger(
                        CronExpressionTrigger::fromSpec('@daily'),
                    ),
                    new SendDailySalesReports()
                ),
                RecurringMessage::cron('3 8 * * 1', new CleanUpOldSalesReport())
            );
    }
}

So, this RecurringMessage will encompass both the trigger, defining the generation frequency of the message, and the message itself, the one to be processed by a specific handler.

But what is interesting to know is that it also provides you with the ability to generate your message(s) dynamically.

A Dynamic Vision for the Messages Generated

This proves particularly useful when the message depends on data stored in databases or third-party services.

Following the previous example of reports generation: they depend on customer requests. Depending on the specific demands, any number of reports may need to be generated at a defined frequency. For these dynamic scenarios, it gives you the capability to dynamically define our message(s) instead of statically. This is achieved by defining a CallbackMessageProvider.

Essentially, this means you can dynamically, at runtime, define your message(s) through a callback that gets executed each time the scheduler transport checks for messages to be generated:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// src/Scheduler/SaleTaskProvider.php
namespace App\Scheduler;

#[AsSchedule('uptoyou')]
class SaleTaskProvider implements ScheduleProviderInterface
{
    public function getSchedule(): Schedule
    {
        return $this->schedule ??= (new Schedule())
            ->with(
                RecurringMessage::trigger(
                    new ExcludeHolidaysTrigger(
                        CronExpressionTrigger::fromSpec('@daily'),
                    ),
                // instead of being static as in the previous example
                new CallbackMessageProvider([$this, 'generateReports'], 'foo')),
                RecurringMessage::cron(‘3 8 * * 1’, new CleanUpOldSalesReport())
            );
    }

    public function generateReports(MessageContext $context)
    {
        // ...
        yield new SendDailySalesReports();
        yield new ReportSomethingReportSomethingElse();
    }
}

Exploring Alternatives for Crafting your Recurring Messages

There is also another way to build a RecurringMessage, and this can be done by adding one of these attributes to a service or a command: AsPeriodicTask and AsCronTask.

For both of these attributes, you have the ability to define the schedule to use via the scheduleoption. By default, the default named schedule will be used. Also, by default, the __invoke method of your service will be called but, it's also possible to specify the method to call via the methodoption and you can define arguments via argumentsoption if necessary.

1
2
3
4
5
6
7
8
9
10
11
12
13

// src/Scheduler/Task/SendDailySalesReports.php
namespace App\Scheduler\Task;

use Symfony\Component\Scheduler\Attribute\AsCronTask;

#[AsCronTask('0 0 * * *')]
class SendDailySalesReports
{
    public function __invoke()
    {
        // ...
    }
}

1
2
3
4
5
6
7
8

// adds randomly up to 6 seconds to the trigger time to avoid load spikes
#[AsCronTask('0 0 * * *', jitter: 6)]

// defines the method name to call instead as well as the arguments to pass to it
#[AsCronTask('0 0 * * *', method: 'sendEmail', arguments: ['email' => 'admin@example.com'])]

// defines the timezone to use
#[AsCronTask('0 0 * * *', timezone: 'Africa/Malabo')]

1
2
3
4
5
6
7
8
9
10
11
12
13

// src/Scheduler/Task/SendDailySalesReports.php
namespace App\Scheduler\Task;

use Symfony\Component\Scheduler\Attribute\AsPeriodicTask;

#[AsPeriodicTask(frequency: '1 day', from: '2022-01-01', until: '2023-06-12')]
class SendDailySalesReports
{
    public function __invoke()
    {
        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// the frequency can be defined as an integer representing the number of seconds
#[AsPeriodicTask(frequency: 86400)]

// adds randomly up to 6 seconds to the trigger time to avoid load spikes
#[AsPeriodicTask(frequency: '1 day', jitter: 6)]

// defines the method name to call instead as well as the arguments to pass to it
#[AsPeriodicTask(frequency: '1 day', method: 'sendEmail', arguments: ['email' => 'admin@symfony.com'])]
class SendDailySalesReports
{
    public function sendEmail(string $email): void
    {
        // ...
    }
}

Modifying Scheduled Messages in Real-Time

While planning a schedule in advance is beneficial, it is rare for a schedule to remain static over time. After a certain period, some RecurringMessages may become obsolete, while others may need to be integrated into the planning.

As a general practice, to alleviate a heavy workload, the recurring messages in the schedules are stored in memory to avoid recalculation each time the scheduler transport generates messages. However, this approach can have a flip side.

Following the same report generation example as above, the company might do some promotions during specific periods (and they need to be communicated repetitively throughout a given timeframe) or the deletion of old reports needs to be halted under certain circumstances.

This is why the Scheduler incorporates a mechanism to dynamically modify the schedule and consider all changes in real-time.

Strategies for Adding, Removing, and Modifying Entries within the Schedule

The schedule provides you with the ability to add(), remove(), or clear() all associated recurring messages, resulting in the reset and recalculation of the in-memory stack of recurring messages.

For instance, for various reasons, if there's no need to generate a report, a callback can be employed to conditionally skip generating of some or all reports.

However, if the intention is to completely remove a recurring message and its recurrence, the Schedule offers a remove() or a removeById() method. This can be particularly useful in your case, especially if you need to halt the generation of the recurring message, which involves deleting old reports.

In your handler, you can check a condition and, if affirmative, access the Schedule and invoke this method:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

// src/Scheduler/SaleTaskProvider.php
namespace App\Scheduler;

#[AsSchedule('uptoyou')]
class SaleTaskProvider implements ScheduleProviderInterface
{
    public function getSchedule(): Schedule
    {
        $this->removeOldReports = RecurringMessage::cron(‘3 8 * * 1’, new CleanUpOldSalesReport());

        return $this->schedule ??= (new Schedule())
            ->with(
                // ...
                $this->removeOldReports;
            );
    }

    // ...

    public function removeCleanUpMessage()
    {
        $this->getSchedule()->getSchedule()->remove($this->removeOldReports);
    }
}

// src/Scheduler/Handler/CleanUpOldSalesReportHandler.php
namespace App\Scheduler\Handler;

#[AsMessageHandler]
class CleanUpOldSalesReportHandler
{
    public function __invoke(CleanUpOldSalesReport $cleanUpOldSalesReport): void
    {
        // do some work here...

        if ($isFinished) {
            $this->mySchedule->removeCleanUpMessage();
        }
    }
}

Nevertheless, this system may not be the most suitable for all scenarios. Also, the handler should ideally be designed to process the type of message it is intended for, without making decisions about adding or removing a new recurring message.

For instance, if, due to an external event, there is a need to add a recurrent message aimed at deleting reports, it can be challenging to achieve within the handler. This is because the handler will no longer be called or executed once there are no more messages of that type.

However, the Scheduler also features an event system that is integrated into a Symfony full-stack application by grafting onto Symfony Messenger events. These events are dispatched through a listener, providing a convenient means to respond.

A Strategic Event Handling

The goal is to provide flexibility in deciding when to take action while preserving decoupling. Three primary event types have been introduced types

• PRE_RUN_EVENT
• POST_RUN_EVENT
• FAILURE_EVENT

Access to the schedule is a crucial feature, allowing effortless addition or removal of message types. Additionally, it will be possible to access the currently processed message and its message context.

In consideration of our scenario, you can listen to the PRE_RUN_EVENT and check if a certain condition is met. For instance, you might decide to add a recurring message for cleaning old reports again, with the same or different configurations, or add any other recurring message(s).

If you had chosen to handle the deletion of the recurring message, you could have done so in a listener for this event. Importantly, it reveals a specific feature shouldCancel() that allows you to prevent the message of the deleted recurring message from being transferred and processed by its handler:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

// src/Scheduler/SaleTaskProvider.php
namespace App\Scheduler;

#[AsSchedule('uptoyou')]
class SaleTaskProvider implements ScheduleProviderInterface
{
    public function __construct(private EventDispatcherInterface $dispatcher)
    {
    }

    public function getSchedule(): Schedule
    {
        $this->removeOldReports = RecurringMessage::cron('3 8 * * 1', new CleanUpOldSalesReport());

        return $this->schedule ??= (new Schedule($this->dispatcher))
            ->with(
                // ...
            )
            ->before(function(PreRunEvent $event) {
                $message = $event->getMessage();
                $messageContext = $event->getMessageContext();

                // can access the schedule
                $schedule = $event->getSchedule()->getSchedule();

                // can target directly the RecurringMessage being processed
                $schedule->removeById($messageContext->id);

                // allow to call the ShouldCancel() and avoid the message to be handled
                $event->shouldCancel(true);
            })
            ->after(function(PostRunEvent $event) {
                // Do what you want
            })
            ->onFailure(function(FailureEvent $event) {
                // Do what you want
            });
    }
}

Scheduler Events

1
2
3
4
5
6
7
8
9
10
11
12
13
14

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Scheduler\Event\PreRunEvent;

public function onMessage(PreRunEvent $event): void
{
    $schedule = $event->getSchedule();
    $context = $event->getMessageContext();
    $message = $event->getMessage();

    // do something with the schedule, context or message

    // and/or cancel message
    $event->shouldCancel(true);
}

1

$ php bin/console debug:event-dispatcher "Symfony\Component\Scheduler\Event\PreRunEvent"

1
2
3
4
5
6
7
8
9
10
11

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Scheduler\Event\PostRunEvent;

public function onMessage(PostRunEvent $event): void
{
    $schedule = $event->getSchedule();
    $context = $event->getMessageContext();
    $message = $event->getMessage();

    // do something with the schedule, context or message
}

1

$ php bin/console debug:event-dispatcher "Symfony\Component\Scheduler\Event\PostRunEvent"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Symfony\Component\Scheduler\Event\FailureEvent;

public function onMessage(FailureEvent $event): void
{
    $schedule = $event->getSchedule();
    $context = $event->getMessageContext();
    $message = $event->getMessage();

    $error = $event->getError();

    // do something with the schedule, context, message or error (logging, ...)

    // and/or ignore failure event
    $event->shouldIgnore(true);
}

1

$ php bin/console debug:event-dispatcher "Symfony\Component\Scheduler\Event\FailureEvent"

Running a Worker

After defining and attaching your recurring messages to a schedule, you'll need a mechanism to generate and consume the messages according to their defined frequencies. To do that, the Scheduler component uses the messenger:consume command from the Messenger component:

1
2
3
4

$ php bin/console messenger:consume scheduler_nameofyourschedule

# use -vv if you need details about what's happening
$ php bin/console messenger:consume scheduler_nameofyourschedule -vv

Creating a Consumer Programmatically

An alternative to the previous solution is to create and call a worker that will consume the messages. The component comes with a ready-to-use worker named Scheduler that you can use in your code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

use Symfony\Component\Scheduler\Scheduler;

$schedule = (new Schedule())
    ->with(
        RecurringMessage::trigger(
            new ExcludeHolidaysTrigger(
                CronExpressionTrigger::fromSpec('@daily'),
            ),
            new SendDailySalesReports()
        ),
    );

$scheduler = new Scheduler(handlers: [
    SendDailySalesReports::class => new SendDailySalesReportsHandler(),
    // add more handlers if you have more message types
], schedules: [
    $schedule,
    // the scheduler can take as many schedules as you need
]);

// finally, run the scheduler once it's ready
$scheduler->run();