Планирование задания

Запуск в очередь ставит метод schedule() объекта задания. Само задание (sTask) создают один раз — скриптом сборки, установщиком пакета или в админке: Создание задания.

<?php
$path = $modx->getOption('scheduler.core_path', null, $modx->getOption('core_path') . 'components/scheduler/');
$scheduler = $modx->getService('scheduler', 'Scheduler', $path . 'model/scheduler/');
if (!($scheduler instanceof Scheduler)) {
    return 'Не удалось получить сервис планировщика.';
}

// Пространство имён «mycmp», название задания «dosomething»
$task = $scheduler->getTask('mycmp', 'dosomething');

if ($task instanceof sTask) {
    $run = $task->schedule('+10 minutes', [
        'client' => 15,
    ]);
}

getTask() ищет задание по паре «пространство имён + название» или по числовому идентификатору и возвращает null, если такого нет. Поэтому проверка instanceof в примере не формальность: без неё вызов schedule() упал бы на null.

Два способа получить сервис. getService() работает и в MODX 2, и в MODX 3 — это самый простой вариант для обеих платформ. В MODX 3 сервис уже зарегистрирован при загрузке пространства имён, поэтому там его берут из контейнера: $modx->services->get('scheduler'). Сам компонент выбирает способ по версии платформы:

if ((int) $modx->version['version'] === 2) {
    $path = $modx->getOption('core_path') . 'components/scheduler/model/scheduler/';
    $scheduler = $modx->getService('scheduler', 'Scheduler', $path);
} else {
    $scheduler = $modx->services->get('scheduler');
}

Аргументы schedule()

$task->schedule($when, array $data = [], string $task_key = '');

Аргумент	Назначение
$when	Когда выполнить: метка времени UNIX или строка для strtotime() — +10 minutes, +14 days, 2026-12-31 23:00. Строка нужна английская: русских слов strtotime() не понимает
$data	Массив, который задание получит в $scriptProperties
$task_key	Произвольная метка запуска, до 128 символов. На выполнение не влияет: по ней ищут запуск на вкладке «Запланированные запуски» в админке, и она переносится в повторные попытки

Метод создаёт объект sTaskRun и возвращает его — либо false, если запуск не сохранился.

$run = $task->schedule('+1 hour', ['order' => 42], 'order-42-reminder');

if ($run === false) {
    $modx->log(modX::LOG_LEVEL_ERROR, 'Не удалось поставить запуск в очередь');
}

Что дальше происходит с запуском

Запуск ждёт своего времени со статусом «Запланировано». Проход cron переводит его в «Выполняется», а по завершении — в «Успешно» или «Ошибка». Исход определяет само задание: подробности в Разработке заданий. Подхватит запуск не обязательно первый же проход после назначенного времени: за один раз берётся не больше запусков, чем разрешает scheduler.tasks_per_run, поэтому при длинной очереди придётся подождать.

Задание делает циклическим его собственное поле recurring. У такого задания после успешного запуска в очередь встаёт следующий — через interval, то есть такую же строку для strtotime(), как и в $when. После неудачного цикл останавливается, пока не включена настройка scheduler.recurring_on_failure (Системные настройки); с ней следующий запуск встаёт через тот же интервал.

Повторные попытки — это другой механизм, и настройка цикла им не управляет. Если у задания задано max_retries, упавший запуск будет повторён: в очередь встанет новый запуск с теми же данными, через retry_delay секунд, и так пока попытки не исчерпаются. Удачная попытка считается успешным запуском, так что цикл циклического задания с неё возобновится. Поля задания описаны в Создании задания.