Триггеры выражений Cron

Прежде чем использовать триггеры cron, необходимо установить следующую зависимость:

1

$ composer require dragonmantank/cron-expression

Затем определите дату/время триггера, используя тот же синтаксис, что и в утилите командной строки cron:

1
2
3
4

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

// опционально вы можете определить часовой пояс, используемый выражением cron
RecurringMessage::cron('* * * * *', new Message(), new \DateTimeZone('Africa/Malabo'));

Вы также можете использовать некоторые специальные значения, которые представляют собой распространенные выражения cron:

• @yearly, @annually - Запускать раз в год, в полночь 1го января - 0 0 1 1 *
• @monthly - Запускать раз в месяц, в полночь, первого числа месяца - 0 0 1 * *
• @weekly - Запускать раз в неделю, в полночь в воскресенье - 0 0 * * 0
• @daily, @midnight - Запускать раз в день, в полночь - 0 0 * * *
• @hourly - Запускать раз в час, в первую минуту - 0 * * * *

Например:

1

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

1

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

Периодические триггеры

Эти триггеры позволяют конфигурировать частоты с использованием различных типов данных (string, integer, DateInterval). Они также поддерживают относительные форматы, определенные функциями PHP datetime:

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);

Пользовательские триггеры

Пользовательские триггеры позволяют динамически конфигурировать любую частоту. Они создаются как сервисы, реализующие TriggerInterface.

Например, если вы хотите отправлять отчеты клиентам ежедневно, за исключением праздничных периодов:

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)
    {
    }

    // использовать этот метод, чтобы дать красиво отображаемое имя для
    // идентификации вашего триггера (облегчает отладку)
    public function __toString(): string
    {
        return $this->inner.' (except holidays)';
    }

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

        // зациклить, пока вы не получите следующую дату запуска, и это не будет праздником
        while (!$this->isHoliday($nextRun) {
            $nextRun = $this->inner->getNextRunDate($nextRun);
        }

        return $nextRun;
    }

    private function isHoliday(\DateTimeImmutable $timestamp): bool
    {
        // добавить некоторую логику, чтобы определить, является ли заданная $timestamp праздником
        // вернуть true, если явялется, false - в других случаях
    }
}

Затем, определите ваше повторяющееся сообщение:

1
2
3
4
5
6

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

Наконец, повторяющиеся сообщения должны быть прикреплены к расписанию:

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())
            );
    }
}

Таким образом, это RecurringMessage будет включать в себя как триггер, определяющий частоту генерирования сообщения, так и само сообщение, которое будет обрабатываться определенным обработчиком.

Но что интересно знать, так это то, что он также предоставляет вам возможность генерировать сообщения динамически.

Динамическое видение для сгенерированных сообщений

Это особенно полезно, когда сообщение зависит от данных, хранящихся в базах данных или сторонних сервисах.

В продолжение предыдущего примера с генерированием отчетов: они зависят от запросов клиентов. В зависимости от конкретных требований может потребоваться создание любого количества отчетов с определенной периодичностью. Для таких динамических сценариев система предоставляет возможность динамически определять наше(и) сообщение(я), а не статически. Это достигается путем определения CallbackMessageProvider.

По сути, это означает, что вы можете динамически, во время выполнения, определить ваше(и) сообщение(я) через обратный вызов, который будет выполняться каждый раз, когда транспорт планировщика проверяет наличие сообщений для генерирования:

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'),
                    ),
                // вместо того, чтобы быть статичным, как в предыдущем примере
                new CallbackMessageProvider([$this, 'generateReports'], 'foo')),
                RecurringMessage::cron(‘3 8 * * 1’, new CleanUpOldSalesReport())
            );
    }

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

Исследование альтернатив для создания ваших повторяющихся сообщений

Существует также другой способ создания RecurringMessage, и это можно сделать добавив один из этих атрибутов к сервису или команде: AsPeriodicTask и AsCronTask.

Для обоих атрибутов у вас есть возможность определить расписание, которое будет использоваться с помощью опции schedule. По умолчанию будет использоваться расписание с именем default. Также по умолчанию будет вызван метод __invoke вашего сервиса, но также можно указать метод для вызова через опцию method. и при необходимости вы можете указать аргументы через опцию arguments.

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

// рандомно добавляет до 6 секунд к времени триггера, чтобы избежать скачков нагрузки
#[AsCronTask('0 0 * * *', jitter: 6)]

// определяет имя метода, который нужно вызвать вместо него, а также аргументы для передачи ему
#[AsCronTask('0 0 * * *', method: 'sendEmail', arguments: ['email' => 'admin@example.com'])]

// определяет часовой пояс для использования
#[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
16
17
18

// частота может быть определена как целое число, представляющее количество секунд
#[AsPeriodicTask(frequency: 86400)]

// рандомно добавляет до 6 секунд к времени триггера, чтобы избежать скачков нагрузки
#[AsPeriodicTask(frequency: '1 day', jitter: 6)]

// определяет имя метода, который будет вызываться вместо него, а также аргументы для передачи ему
#[AsPeriodicTask(frequency: '1 day', method: 'sendEmail', arguments: ['email' => 'admin@symfony.com'])]
class SendDailySalesReports
{
    public function sendEmail(string $email): void
    {
        // ...
    }
}

// определяет часовой пояс для использования
#[AsPeriodicTask(frequency: '1 day', timezone: 'Africa/Malabo')]

Изменение запланированных сообщений в реальном времени

Хотя планировать расписание заранее полезно, редко когда расписание остается статичным в течение долгого времени. По истечении определенного периода некоторые RecurringMessages могут устареть, в то время как другие могут потребовать внесения в планирование.

Как правило, для облегчения большой нагрузки повторяющиеся сообщения в расписаниях хранятся в памяти, чтобы избежать повторного вычисления каждый раз, когда планировщик транспорта генерирует сообщения. Однако такой подход может иметь и обратную сторону.

Следуя примеру с генерированием отчетов, описанному выше, компания может проводить некоторые рекламные акции в определенные периоды (и о них нужно сообщать многократно в течение определенного периода времени) или удаление старых отчетов должно быть остановлено при определенных обстоятельствах.

Именно поэтому в Scheduler встроен механизм динамической модификации расписания и он учитывает все изменения в режиме реального времени.

Стратегии для добавления, удаления и изменения записей в расписании

Расписание предоставляет вам возможность
add(), remove(), или clear() все связанные с ним повторяющиеся сообщения, что приводит к сбросу и повторному вычислению стека повторяющихся сообщений в памяти.

Например, по разным причинам, если нет необходимости генерировать отчет, можно использовать обратный вызов для условного пропуска генерирования некоторых или всех отчетов.

Однако если необходимо полностью удалить повторяющееся сообщение и его повторение, Schedule предлагает метод
remove() или removeById(). Это может быть особенно полезным в вашем случае, особенно если вам нужно остановить генерирование повторяющихся сообщений, что подразумевает удаление старых отчетов.

В своем обработчике вы можете проверить условие и, если оно выполнено, обратиться к файлу Schedule и вызвать этот метод:

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/.php
namespace App\Scheduler\Handler;

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

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

Тем не менее, эта система может оказаться не самой подходящей для всех сценариев. Кроме того, в идеале обработчик должен быть предназначен для обработки того типа сообщений, для которого он предназначен, без принятия решений о добавлении или удалении нового повторяющегося сообщения.

Например, если в результате внешнего события возникла необходимость добавить повторяющееся сообщения, направленного на удаление отчетов, это может быть непросто сделать в рамках обработчика. Это связано с тем, что обработчик больше не будет вызываться или выполняться, как только больше не будет сообщений этого типа.

Однако в планировщике также имеется система событий, которая интегрирована в полностековое приложение Symfony путем прививки к событиям Symfony Messenger. Эти события развертываются через слушателя, предоставляя удобные средства для реагирования.

Стратегическое управление событиями

Цель состоит в том, чтобы обеспечить гибкость при принятии решения о том, когда следует действовать,
при сохранении развязки. Представлены три основных типа событий

• PRE_RUN_EVENT
• POST_RUN_EVENT
• FAILURE_EVENT

Доступ к расписанию - важнейшая функция, позволяющая легко добавлять или
удалять типы сообщений. Кроме того, можно будет получить доступ к текущему обрабатываемому сообщению и его контексту.

В нашем сценарии вы можете прослушать PRE_RUN_EVENT и проверить, выполняется ли определенное условие. Например, вы можете решить добавить повторяющееся сообщение для повторной очистки старых отчетов с той же или другой конфигурациями или добавить любое другое повторяющееся сообщение (сообщения).

Если бы вы решили обработать удаление повторяющегося сообщения, вы могли бы сделать это в слушателе данного события. Важно отметить, что оно раскрывает специфическую функцию shouldCancel(),
которая позволяет предотвратить передачу и обработку удаленного повторяющегося сообщения его обработчиком:

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

// 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(
                // ...
            );
            ->before(function(PreRunEvent $event) {
                $message = $event->getMessage();
                $messageContext = $event->getMessageContext();

                // может получить доступ к расписанию
                $schedule = $event->getSchedule()->getSchedule();

                // можеть быть напрямую нацелен на обрабатываемое RecurringMessage
                $schedule->removeById($messageContext->id);

                // разрешить вызов ShouldCancel() и избежать обработки сообщения
                    $event->shouldCancel(true);
            }
            ->after(function(PostRunEvent $event) {
                // Делайте, что хотите
            }
            ->onFailure(function(FailureEvent $event) {
                // Делайте, что хотите
            }
    }
}

События Scheduler

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();

    // сделать что-то с раписанием, контекстом или сообщением

    // и/или отменить сообщение
    $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();

    // сделать что-то с расписанием, контекстом или сообщением
}

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();

    // сделать что-то с расписанием, контекстом, сообщением или ошибкой (логирование, ...)

    // и/или игнорировать событие неудачи
    $event->shouldIgnore(true);
}

1

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

Запуск работника

После определения и прикрепления повторяющихся сообщений к расписанию, вам понадобится механизм для генерирования и потребления сообщений в соответствии с заданной частотой. Для этого компонент Scheduler использует команду messenger:consume из компонента Messenger:

1
2
3
4

$ php bin/console messenger:consume scheduler_nameofyourschedule

# использовать -vv, если вам нужны детали о том, что происходит
$ php bin/console messenger:consume scheduler_nameofyourschedule -vv

Программное создание потребителя

Альтернативой предыдущему решению является создание и вызов работника, который будет потреблять сообщения. Компонент поставляется с готовым работником с именем Scheduler, который вы можете использовать в своем коде:

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(),
    // добавить больше обработчиков, если у вас больше типов сообщений
], schedules: [
    $schedule,
    // планировщик может принимать столько расписаний, сколько вам надо
]);

// наконец, запустите планировщик единожды, когда он будет готов
$scheduler->run();