Scheduler

.. versionadded:: 6.3

The Scheduler component was introduced in Symfony 6.3

The Symfony Scheduler is a powerful and flexible component designed to manage tasks scheduling within your PHP application.

This document focuses on using the Scheduler component in the context of a full stack Symfony application.

Installation

In applications using :ref:`Symfony Flex <symfony-flex>`, run this command to

install the scheduler component:

.. code-block:: terminal

Introduction to the case:

Embarking on a task is one thing, but often, the need to repeat that task looms large. While one could resort to issuing commands and scheduling them with cron jobs, this approach involves external tools and additional configuration. The Symfony Scheduler component emerges as a solution, allowing us to retain control, configuration, and maintenance of task scheduling within our PHP application.

At its core, the principle is straightforward: a task, considered as a message needs to be managed by a service, and this cycle must be repeated.

Does this sound familiar? Think :doc:`Symfony Messenger docs </components/messenger>`.

But while the system of Symfony Messenger proves very useful in various scenarios, there are instances where its capabilities fall short, particularly when dealing with repetitive tasks at regular intervals.

Let's dive into a practical example within the context of a sales company.

Imagine the company's goal is to send diverse sales reports to customers based on the specific reports each customer chooses to receive. In constructing the schedule for this scenario, the following steps are taken:

#. Iterate over reports stored in the database and create a recurring task for each report, considering its unique properties. This task, however, should not be generated during holiday periods.

#. Furthermore, we encounter another critical task that needs scheduling: the periodic cleanup of outdated files that are no longer relevant.

On the basis of a case study in the context of a full stack Symfony application, let's dive in and explore how we can set up our system.

Symfony Scheduler basics:

Differences and parallels between Symfony Messenger and Symfony Scheduler.

The primary goal is to generate and process reports generation while also handling the removal of outdated reports at specified intervals.

As mentioned, this component, even if it's an independent component, it draws its foundation and inspiration from the Symfony Messenger component.

On one hand, it adopts well-established concepts from Symfony Messenger (such as message, handler, bus, transport, etc.). For example, the task of creating a report is considered as a message that will be directed, and processed by the corresponding handler.

However, unlike Symfony Messenger, the messages will not be dispatched in the first instance. Instead, the aim is to create them based on a predefined frequency.

This is where the specific transport in Symfony Scheduler, known as the :class:`Symfony\\Component\\Scheduler\\Messenger\\SchedulerTransport`, plays a crucial role. The transport autonomously generates directly various messages according to the assigned frequencies.

From (Symfony Messenger cycle):

.. image:: /_images/components/messenger/basic_cycle.png

:alt: Symfony Messenger basic cycle

To (Symfony Scheduler cycle):

.. image:: /_images/components/scheduler/scheduler_cycle.png

:alt: Symfony Scheduler basic cycle

In essence, it is crucial to precisely define the message to be conveyed and processed. In Symfony Scheduler, the concept of a message takes on a very particular characteristic; it should be recurrent: It's a :class:`Symfony\\Component\\Scheduler\\RecurringMessage`.

Clarifying the need to define and attach Recurring Messages to a Schedule.

In order to generate various messages based on their defined frequencies, configuration is necessary.

The heart of the scheduling process and its configuration resides in a class that must extend the :class:`Symfony\\Component\\Scheduler\\ScheduleProviderInterface`.

The purpose of this provider is to return a schedule through the method ``getSchedule()`` containing our different recurringMessages.

The class attribute ``AsSchedule``, which by default references the ``default`` named schedule, allows us to register on a particular schedule::

.. tip::

This becomes important when initiating the ``messenger:consume`` command, especially when specifying one or more specific transports.

In Symfony Scheduler, the transport is named ``scheduler_nameofyourschedule``.

The Concept of Recurring Message in Symfony Scheduler

A message associated with a Trigger

First and foremost, a RecurringMessage is a message that will be associated with a trigger.

The trigger is what allows configuring the recurrence frequency of your message. Several options are available to us:

#. It can be a cron expression trigger:

.. configuration-block::

.. code-block:: php

.. tip::

A hashed expressions is a string representing the schedule for a particular command to execute.

Supported hashed expression:

* ``#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 * * * *``

.. tip::

It's possible to add and define a timezone as a 3rd argument

#. It can be a periodicalTrigger through various frequency formats (string / integer / DateInterval)

.. configuration-block::

.. code-block:: php

#. It can be a custom trigger implementing :class:`Symfony\\Component\\Scheduler\\TriggerInterface`

If we go back to our scenario regarding reports generation based on our customer preferences.

If the basic frequency is set to a daily basis, we will need to implement a custom trigger due to the specific requirement of not generating reports during public holiday periods::

Then, we would have to define our RecurringMessage

.. configuration-block::

.. code-block:: php

The RecurringMessages must be attached to a Schedule::

So, this recurring message 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 us with the ability to generate our message 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.

Taking our example of reports generation, it depends 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 us the capability to dynamically define our message instead of statically. This is achieved by wrapping it in a :class:`Symfony\\Component\\Scheduler\\Trigger\\CallbackMessageProvider`.

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

Exploring alternatives for crafting your Recurring Messages.

- Explore alternative methods for creating recurring messages (via attributes).

Managing Scheduled Messages:

Modifying Scheduled Messages in real time

- Emphasize the importance of dynamically modifying scheduled messages.

Exploring Strategies for adding, removing, and modifying entries within the Schedule

- Discuss approaches to add, remove, or modify messages within the schedule.

- Explore actions within a handler and introduce the concept of events in Symfony.

Managing Scheduled Messages via Events:

A strategic event handling

- Explain the different types of events in Symfony (PRE_RUN_EVENT / POST_RUN_EVENT / FAILURE_EVENT)

- Mention the distinctive feature of the PRE_RUN_EVENT to prevent a message from being handled by its designated handler.

Efficient management with Symfony Scheduler:

- Detail the special considerations for efficient management, including caching, locking, and the use of multiple schedules (possibility to scale up your schedules).

- Demonstrate the possibility of redispatching a message.