Планувальник задач · Laravel

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

Планувальник команд Laravel пропонує інший підхід до керування задачами за розкладом. Планувальник дозволяє описувати розклад команд виразно й ланцюжком викликів прямо всередині застосунку. При цьому на сервері потрібен лише один запис cron. Розклад задач зазвичай визначається у файлі routes/console.php.

Визначення розкладу

Усі задачі за розкладом можна визначити у файлі routes/console.php. Почнімо з прикладу. Тут ми запланували замикання, яке викликатиметься щодня опівночі. Усередині замикання виконується запит до бази даних, що очищає таблицю:

<?php

use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schedule;

Schedule::call(function () {
    DB::table('recent_users')->delete();
})->daily();

Окрім замикань, можна планувати обʼєкти, які можна викликати. Це звичайні PHP-класи з методом __invoke:

Schedule::call(new DeleteRecentUsers)->daily();

Якщо ви хочете лишити файл routes/console.php тільки для визначення команд, скористайтеся методом withSchedule у файлі bootstrap/app.php. Цей метод приймає замикання, яке отримує екземпляр планувальника:

use Illuminate\Console\Scheduling\Schedule;

->withSchedule(function (Schedule $schedule) {
    $schedule->call(new DeleteRecentUsers)->daily();
})

Щоб переглянути перелік запланованих задач і час їхнього наступного запуску, скористайтеся Artisan-командою schedule:list:

php artisan schedule:list

Планування Artisan-команд

Крім замикань, планувати можна Artisan-команди та системні команди. Наприклад, метод command дозволяє запланувати Artisan-команду за її назвою або класом.

Коли ви плануєте Artisan-команду за назвою класу, можна передати масив додаткових аргументів командного рядка, які буде передано команді під час виклику:

use App\Console\Commands\SendEmailsCommand;
use Illuminate\Support\Facades\Schedule;

Schedule::command('emails:send Taylor --force')->daily();

Schedule::command(SendEmailsCommand::class, ['Taylor', '--force'])->daily();

Планування Artisan-команд із замиканням

Якщо потрібно запланувати Artisan-команду, визначену замиканням, додайте методи планування ланцюжком після визначення команди:

Artisan::command('delete:recent-users', function () {
    DB::table('recent_users')->delete();
})->purpose('Delete recent users')->daily();

Якщо команді-замиканню треба передати аргументи, передайте їх методу schedule:

Artisan::command('emails:send {user} {--force}', function ($user) {
    // ...
})->purpose('Send emails to the specified user')->schedule(['Taylor', '--force'])->daily();

Планування завдань у черзі

Метод job планує завдання (job) у черзі. Це зручніший спосіб, ніж використовувати метод call із замиканням, яке ставить завдання в чергу:

use App\Jobs\Heartbeat;
use Illuminate\Support\Facades\Schedule;

Schedule::job(new Heartbeat)->everyFiveMinutes();

Методу job можна передати необовʼязкові другий і третій аргументи, які вказують назву черги та зʼєднання черги для постановки завдання:

use App\Jobs\Heartbeat;
use Illuminate\Support\Facades\Schedule;

// Відправити завдання в чергу "heartbeats" на зʼєднанні "sqs"...
Schedule::job(new Heartbeat, 'heartbeats', 'sqs')->everyFiveMinutes();

Планування команд оболонки

Метод exec передає команду операційній системі:

use Illuminate\Support\Facades\Schedule;

Schedule::exec('node /home/forge/script.js')->daily();

Варіанти частоти запуску

Кілька прикладів налаштування інтервалів ми вже бачили. Але доступних частот значно більше:

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

use Illuminate\Support\Facades\Schedule;

// Раз на тиждень у понеділок о 13:00...
Schedule::call(function () {
    // ...
})->weekly()->mondays()->at('13:00');

// Щогодини з 8:00 до 17:00 у будні...
Schedule::command('foo')
    ->weekdays()
    ->hourly()
    ->timezone('America/Chicago')
    ->between('8:00', '17:00');

Перелік додаткових обмежень розкладу наведено нижче:

Обмеження за днями

Метод days обмежує виконання задачі конкретними днями тижня. Наприклад, команду можна запускати щогодини по неділях і середах:

use Illuminate\Support\Facades\Schedule;

Schedule::command('emails:send')
    ->hourly()
    ->days([0, 3]);

Замість чисел можна використати константи класу Illuminate\Console\Scheduling\Schedule:

use Illuminate\Support\Facades;
use Illuminate\Console\Scheduling\Schedule;

Facades\Schedule::command('emails:send')
    ->hourly()
    ->days([Schedule::SUNDAY, Schedule::WEDNESDAY]);

Обмеження за проміжком часу

Метод between обмежує виконання задачі за часом доби:

Schedule::command('emails:send')
    ->hourly()
    ->between('7:00', '22:00');

Так само метод unlessBetween виключає виконання задачі на певний проміжок часу:

Schedule::command('emails:send')
    ->hourly()
    ->unlessBetween('23:00', '4:00');

Обмеження за перевіркою на істинність

Метод when обмежує виконання задачі результатом заданої перевірки на істинність. Іншими словами, якщо передане замикання повертає true, задача виконається за умови, що жодне інше обмеження не завадить її запуску:

Schedule::command('emails:send')->daily()->when(function () {
    return true;
});

Метод skip можна розглядати як протилежність when. Якщо skip повертає true, задачу за розкладом не буде виконано:

Schedule::command('emails:send')->daily()->skip(function () {
    return true;
});

Коли методи when вибудовані в ланцюжок, команда за розкладом виконається тільки тоді, коли всі умови when повернуть true.

Обмеження за середовищем

Метод environments дозволяє виконувати задачі лише в заданих середовищах (визначених змінною середовища APP_ENV):

Schedule::command('emails:send')
    ->daily()
    ->environments(['staging', 'production']);

Часові пояси

За допомогою методу timezone можна вказати, що час задачі за розкладом слід трактувати в заданому часовому поясі:

use Illuminate\Support\Facades\Schedule;

Schedule::command('report:generate')
    ->timezone('America/New_York')
    ->at('2:00')

Якщо ви щоразу призначаєте той самий часовий пояс усім задачам, задайте його для всіх розкладів через опцію schedule_timezone у конфігураційному файлі app:

'timezone' => 'UTC',

'schedule_timezone' => 'America/Chicago',

Увага! Памʼятайте, що в деяких часових поясах діє перехід на літній час. Під час такого переходу задача за розкладом може виконатися двічі або взагалі не виконатися. Тому ми радимо по змозі уникати планування з привʼязкою до часового поясу.

Запобігання накладанню задач

Типово задачі за розкладом запускаються, навіть якщо попередній екземпляр задачі ще працює. Щоб цього уникнути, скористайтеся методом withoutOverlapping:

use Illuminate\Support\Facades\Schedule;

Schedule::command('emails:send')->withoutOverlapping();

У цьому прикладі Artisan-команда emails:send запускатиметься щохвилини, якщо вона ще не виконується. Метод withoutOverlapping особливо корисний для задач, тривалість яких сильно коливається і яку неможливо передбачити наперед.

За потреби можна вказати, скільки хвилин має минути до того, як блокування «без накладання» спливе. Типово блокування діє 24 години:

Schedule::command('emails:send')->withoutOverlapping(10);

Під капотом метод withoutOverlapping використовує кеш застосунку для отримання блокувань. За потреби ці блокування в кеші можна очистити Artisan-командою schedule:clear-cache. Зазвичай це потрібно тільки тоді, коли задача зависла через непередбачувану проблему на сервері.

Запуск задач лише на одному сервері

Увага! Щоб скористатися цією можливістю, застосунок має використовувати драйвер кешу database, memcached, dynamodb або redis як типовий драйвер кешу. До того ж усі сервери мають працювати з одним центральним сервером кешу.

Якщо планувальник застосунку працює на кількох серверах, виконання задачі можна обмежити одним сервером. Скажімо, у вас є задача, яка щопʼятниці ввечері генерує новий звіт. Якщо планувальник працює на трьох робочих серверах, задача виконається на всіх трьох і згенерує звіт тричі. Погано!

Щоб задача виконувалася лише на одному сервері, використайте метод onOneServer під час її визначення. Перший сервер, який отримає задачу, встановить атомарне блокування на завдання і не дасть іншим серверам виконати ту саму задачу одночасно:

use Illuminate\Support\Facades\Schedule;

Schedule::command('report:generate')
    ->fridays()
    ->at('17:00')
    ->onOneServer();

Метод useCache дозволяє змінити сховище кешу, яке планувальник використовує для атомарних блокувань, потрібних задачам на одному сервері:

Schedule::useCache('database');

Іменування завдань для одного сервера

Іноді те саме завдання треба відправляти з різними параметрами, але кожну його варіацію все одно виконувати на одному сервері. Для цього призначте кожному визначенню розкладу унікальну назву через метод name:

Schedule::job(new CheckUptime('https://laravel.com'))
    ->name('check_uptime:laravel.com')
    ->everyFiveMinutes()
    ->onOneServer();

Schedule::job(new CheckUptime('https://vapor.laravel.com'))
    ->name('check_uptime:vapor.laravel.com')
    ->everyFiveMinutes()
    ->onOneServer();

Так само замиканням за розкладом треба призначати назву, якщо вони мають виконуватися на одному сервері:

Schedule::call(fn () => User::resetApiRequestCount())
    ->name('reset-api-request-count')
    ->daily()
    ->onOneServer();

Фонові задачі

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

use Illuminate\Support\Facades\Schedule;

Schedule::command('analytics:report')
    ->daily()
    ->runInBackground();

Увага! Метод runInBackground можна використовувати лише під час планування задач методами command та exec.

Режим обслуговування

Задачі за розкладом не виконуються, коли застосунок перебуває в режимі обслуговування: задачі не повинні заважати незавершеним роботам на сервері. Але якщо потрібно змусити задачу виконуватися навіть у режимі обслуговування, викличте метод evenInMaintenanceMode під час її визначення:

Schedule::command('emails:send')->evenInMaintenanceMode();

Призупинення задач за розкладом

Обробку задач за розкладом можна тимчасово призупинити без зміни розгорнутого коду за допомогою Artisan-команди schedule:pause:

php artisan schedule:pause

Поки планувальник призупинено, жодна задача за розкладом не виконується. Відновити обробку можна командою schedule:continue:

php artisan schedule:continue

Якщо якась задача має виконуватися навіть під час паузи, позначте її методом evenWhenPaused:

Schedule::command('emails:send')->evenWhenPaused();

Групи розкладу

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

Щоб створити групу задач за розкладом, викличте потрібні методи конфігурації, а за ними метод group. Метод group приймає замикання, яке визначає задачі зі спільною конфігурацією:

use Illuminate\Support\Facades\Schedule;

Schedule::daily()
    ->onOneServer()
    ->timezone('America/New_York')
    ->group(function () {
        Schedule::command('emails:send --force');
        Schedule::command('emails:prune');
    });

Запуск планувальника

Ми навчилися визначати задачі за розкладом, тепер розберімося, як насправді запускати їх на сервері. Artisan-команда schedule:run перевіряє всі ваші задачі за розкладом і визначає, чи треба їх виконати, спираючись на поточний час сервера.

Отже, з планувальником Laravel на сервері потрібен лише один запис у конфігурації cron, який щохвилини запускає команду schedule:run. Якщо ви не знаєте, як додавати записи cron на сервер, розгляньте керовану платформу на кшталт Laravel Cloud, яка візьме виконання задач за розкладом на себе:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

Задачі частіше ніж раз на хвилину

У більшості операційних систем cron-задачі можуть виконуватися максимум раз на хвилину. Проте планувальник Laravel дозволяє планувати задачі з коротшими інтервалами, аж до однієї секунди:

use Illuminate\Support\Facades\Schedule;

Schedule::call(function () {
    DB::table('recent_users')->delete();
})->everySecond();

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

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

use App\Jobs\DeleteRecentUsers;

Schedule::job(new DeleteRecentUsers)->everyTenSeconds();

Schedule::command('users:delete')->everyTenSeconds()->runInBackground();

Переривання задач із субхвилинним інтервалом

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

Щоб перервати виклики schedule:run, які вже виконуються, додайте команду schedule:interrupt до скрипта розгортання. Її слід викликати після завершення розгортання застосунку:

php artisan schedule:interrupt

Запуск планувальника локально

Зазвичай запис cron для планувальника не додають на локальну машину розробника. Замість цього використовуйте Artisan-команду schedule:work. Вона працює в передньому плані й викликає планувальник щохвилини, доки ви не завершите команду. Якщо визначені субхвилинні задачі, планувальник працюватиме всередині кожної хвилини, щоб їх обробити:

php artisan schedule:work

Вивід задач

Планувальник Laravel має кілька зручних методів для роботи з виводом задач за розкладом. Метод sendOutputTo надсилає вивід у файл для подальшого перегляду:

use Illuminate\Support\Facades\Schedule;

Schedule::command('emails:send')
    ->daily()
    ->sendOutputTo($filePath);

Якщо вивід треба дописувати до наявного файлу, скористайтеся методом appendOutputTo:

Schedule::command('emails:send')
    ->daily()
    ->appendOutputTo($filePath);

Метод emailOutputTo надсилає вивід на вказану електронну адресу. Перед цим треба налаштувати поштові сервіси Laravel:

Schedule::command('report:generate')
    ->daily()
    ->sendOutputTo($filePath)
    ->emailOutputTo('taylor@example.com');

Якщо ви хочете отримувати вивід поштою тільки тоді, коли Artisan-команда або системна команда за розкладом завершилася з ненульовим кодом виходу, використайте метод emailOutputOnFailure:

Schedule::command('report:generate')
    ->daily()
    ->emailOutputOnFailure('taylor@example.com');

Увага! Методи emailOutputTo, emailOutputOnFailure, sendOutputTo та appendOutputTo доступні лише для методів command та exec.

Хуки задач

Методи before і after дозволяють задати код, який виконається до і після виконання задачі за розкладом:

use Illuminate\Support\Facades\Schedule;

Schedule::command('emails:send')
    ->daily()
    ->before(function () {
        // Задача ось-ось виконається...
    })
    ->after(function () {
        // Задача виконана...
    });

Методи onSuccess і onFailure задають код, який виконається у разі успіху або невдачі задачі за розкладом. Невдача означає, що Artisan-команда або системна команда завершилася з ненульовим кодом виходу:

Schedule::command('emails:send')
    ->daily()
    ->onSuccess(function () {
        // Задача виконалася успішно...
    })
    ->onFailure(function () {
        // Задача завершилася невдало...
    });

Якщо команда щось вивела, цей вивід доступний у хуках after, onSuccess та onFailure: вкажіть тип Illuminate\Support\Stringable для аргументу $output у замиканні хука:

use Illuminate\Support\Stringable;

Schedule::command('emails:send')
    ->daily()
    ->onSuccess(function (Stringable $output) {
        // Задача виконалася успішно...
    })
    ->onFailure(function (Stringable $output) {
        // Задача завершилася невдало...
    });

Пінг URL-адрес

За допомогою методів pingBefore і thenPing планувальник може автоматично пінгувати задану URL-адресу до або після виконання задачі. Це корисно, щоб повідомити зовнішній сервіс, наприклад Envoyer, що задача за розкладом почалася або завершилася:

Schedule::command('emails:send')
    ->daily()
    ->pingBefore($url)
    ->thenPing($url);

Методи pingOnSuccess і pingOnFailure пінгують задану URL-адресу лише у разі успіху або невдачі задачі. Невдача означає, що Artisan-команда або системна команда за розкладом завершилася з ненульовим кодом виходу:

Schedule::command('emails:send')
    ->daily()
    ->pingOnSuccess($successUrl)
    ->pingOnFailure($failureUrl);

Методи pingBeforeIf, thenPingIf, pingOnSuccessIf та pingOnFailureIf пінгують задану URL-адресу тільки тоді, коли задана умова дорівнює true:

Schedule::command('emails:send')
    ->daily()
    ->pingBeforeIf($condition, $url)
    ->thenPingIf($condition, $url);

Schedule::command('emails:send')
    ->daily()
    ->pingOnSuccessIf($condition, $successUrl)
    ->pingOnFailureIf($condition, $failureUrl);

Події

Під час роботи планувальника Laravel відправляє низку подій. Ви можете визначити слухачів для будь-якої з них: