Тригери виразів сron

Перед використанням 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
    {
        // зробити якусь роботу тут...

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

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

Наприклад, якщо через зовнішню подію потрібно додати повторюване повідомлення, спрямоване на видалення звітів, це може бути складно зробити в обробнику.
Це пов'язано з тим, що обробник більше не буде викликаний або виконаний, коли більше не буде повідомлень такого типу.

Однак, Scheduler також має систему подій, яка інтегрована у 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) {
                // Зробити те, що ви хочете
            }
    }
}

Події планувальника

1

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

1

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

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