From 12b65f3b04de2a0276338b2e3595bf7f92fb7bbe Mon Sep 17 00:00:00 2001 From: MrYamous Date: Tue, 28 Mar 2023 23:23:28 +0200 Subject: [PATCH 1/2] init scheduler doc --- index.rst | 1 + reference/attributes.rst | 5 ++ scheduler.rst | 129 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 135 insertions(+) create mode 100644 scheduler.rst diff --git a/index.rst b/index.rst index c2ec849c27f..f967fa882f0 100644 --- a/index.rst +++ b/index.rst @@ -54,6 +54,7 @@ Topics profiler rate_limiter routing + scheduler security session setup diff --git a/reference/attributes.rst b/reference/attributes.rst index fe3a211ad6a..e4d6027bfeb 100644 --- a/reference/attributes.rst +++ b/reference/attributes.rst @@ -74,6 +74,11 @@ Routing * :doc:`Route ` +Scheduler +~~~~~~~~~ + +* :ref:`AsSchedule ` + Security ~~~~~~~~ diff --git a/scheduler.rst b/scheduler.rst new file mode 100644 index 00000000000..ec573b216c7 --- /dev/null +++ b/scheduler.rst @@ -0,0 +1,129 @@ +Scheduler +========= + +.. versionadded:: 6.3 + + The Scheduler component was introduced in Symfony 6.3 and is marked + as experimental. + +The Scheduler component provides a way to schedule periodical tasks or handling +recurring messages without using an external tool. + +The component shares somes keys concepts with :ref:`Messenger `. + +Installation +------------ + +You can install the Scheduler component with: + +.. code-block:: terminal + + $ composer require symfony/scheduler + +.. include:: /components/require_autoload.rst.inc + +.. _register-schedule-provider: + +Register a Schedule provider +---------------------------- + +A Schedule provider is a class defining your schedule : which messages should +be processed depending a trigger you choose:: + + namespace App\Schedule; + + use App\Message\EndofTrialMessage; + use Symfony\Component\Messenger\RecurringMessage; + use Symfony\Component\Scheduler\Attribute\AsSchedule; + use Symfony\Component\Scheduler\Schedule; + use Symfony\Component\Schedule\ScheduleProviderInterface; + + #[AsSchedule('trial')] + final class EndOfTrialScheduleProvider implements ScheduleProviderInterface + { + public function getSchedule(string $id): Schedule + { + return (new Schedule()) + ->add(new RecurringMessage::every('1 week', new EndofTrialMessage())) + ; + } + } + +Run the Messenger consumer +-------------------------- + +Scheduler uses the same :ref:`Messenger worker` to consume +messages dispatched by your schedule class. + +You can do this with the ``messenger:consume`` command: + +.. code-block:: terminal + + $ php bin/console messenger:consume scheduler_trial + +Trigger your schedule +--------------------- + +Symfony provides by default two triggers for your schedules : `every` and +`cron`. By extending the provided TriggerInterface you can also create +your own trigger for your app. + +Every +~~~~~ + +This trigger allows you to define you schedule with frequency as text, using +intervals or relative date format allowed by PHP:: + + RecurringMessage::every('10 seconds', $msg); + RecurringMessage::every('1 day', $msg); + RecurringMessage::every('2 weeks', $msg); + + RecurringMessage::every('first day of month', $msg); + RecurringMessage::every('next tuesday', $msg); + +It is possible to specify an exact hour to trigger the schedule with `from` +option:: + + RecurringMessage::every('first day of month', $msg, from: '13:47'); + + // using timezone + RecurringMessage::every('first day of month', $msg, from: '13:47+0400'); + + // using a DateTimeImmutable object + $from = new \DateTimeImmutable('13:47', new \DateTimeZone('Europe/Paris')); + RecurringMessage::every('first day of month', $msg, from: $from); + +If your schedule do not need to run indefinitely, you can use `until` option +to let the Component know when the trigger should stop:: + + RecurringMessage::every('monday', $msg, until: '2023-06-12'); + +Cron +~~~~ + +This trigger can be configured following same rules as the eponymous Unix +utility:: + + // trigger every hour + RecurringMessage::cron('0 * * * *', $msg); + + // trigger every monday at 12:00 + RecurringMessage::cron('0 12 * * 1', $msg); + +.. note:: + + The minimal interval allowed with cron is 1 minute. + +Define your own trigger +~~~~~~~~~~~~~~~~~~~~~~~ + +By implementing the TriggerInterface your can create your own trigger using +``getNextRunDate`` method:: + + final class CustomTrigger implements TriggerInterface + { + public function getNextRunDate(\DateTimeImmutable $run): ?\DateTimeImmutable + { + // your logic + } + } From f9b0c2eabfa6f1be40ae444c5303f332a9c0b7be Mon Sep 17 00:00:00 2001 From: MrYamous Date: Sun, 2 Apr 2023 19:36:42 +0200 Subject: [PATCH 2/2] some fixes --- scheduler.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/scheduler.rst b/scheduler.rst index ec573b216c7..d8ed31da99d 100644 --- a/scheduler.rst +++ b/scheduler.rst @@ -33,10 +33,10 @@ be processed depending a trigger you choose:: namespace App\Schedule; use App\Message\EndofTrialMessage; - use Symfony\Component\Messenger\RecurringMessage; use Symfony\Component\Scheduler\Attribute\AsSchedule; + use Symfony\Component\Scheduler\RecurringMessage; use Symfony\Component\Scheduler\Schedule; - use Symfony\Component\Schedule\ScheduleProviderInterface; + use Symfony\Component\Scheduler\ScheduleProviderInterface; #[AsSchedule('trial')] final class EndOfTrialScheduleProvider implements ScheduleProviderInterface @@ -52,7 +52,7 @@ be processed depending a trigger you choose:: Run the Messenger consumer -------------------------- -Scheduler uses the same :ref:`Messenger worker` to consume +Scheduler uses the same :ref:`Messenger worker ` to consume messages dispatched by your schedule class. You can do this with the ``messenger:consume`` command: