Создание WebCron плагина для Joomla 4 (Task Scheduler Plugin)

Эта статья — дополненный перевод статьи How to Create Joomla Task Scheduler Plugin.

В Joomla! появился планировщик задач начиная с версии 4.1. Он помогает автоматизировать повторяющиеся и рутинные задачи самого широкого спектра, начиная от технического обслуживания и заканчивая сложными синхронизациями по API.

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

Задания CRON (CRON Job): Задание CRON используется для автоматизации повторяющихся задач. Например, для обработки очередей электронной почты, для синхронизации заказов или остатков товаров, обновления цен интернет-магазина, для проверки веб-сайта на наличие проблем и так далее.

Также о технологии WebCron в Joomla 4.1 сообщалось в обзоре Новое в Joomla 4.1 на Хабре, в разделе «WebCron в Joomla 4.1«.

Плагин планировщика задач Joomla 4 (Task Scheduler)

Это стандартный Joomla! плагин с group="task". В нём необходимо использовать TaskPluginTrait.

use Joomla\CMS\Plugin\CMSPlugin; use Joomla\Component\Scheduler\Administrator\Event\ExecuteTaskEvent; use Joomla\Component\Scheduler\Administrator\Task\Status; use Joomla\Component\Scheduler\Administrator\Task\Task; use Joomla\Component\Scheduler\Administrator\Traits\TaskPluginTrait; use Joomla\Event\SubscriberInterface;  class PlgTaskExample extends CMSPlugin implements SubscriberInterface {     use TaskPluginTrait;          protected const TASKS_MAP = array(         'plg_task_do_example' => array(             'langConstPrefix' => 'PLG_TASK_DO_EXAMPLE',             'method' => 'doExample',             'form' => 'do_example'             )         );      protected $autoloadLanguage = true;     protected $app;     protected $db;          public static function getSubscribedEvents(): array     {         return array(             'onTaskOptionsList' => 'advertiseRoutines',             'onExecuteTask' => 'standardRoutineHandler',             'onContentPrepareForm' => 'enhanceTaskItemForm',         );     }          private function doExample(ExecuteTaskEvent $event): int     {         // Code for Tasks                  return Status::OK;     } }

Реализация

Плагин планировщика задач в Joomla 4 должен использовать TaskPluginTrait и определять методы, соответствующие каждой процедуре вместе с константой класса TASKS_MAP для объявления поддерживаемых процедур и связанных с ними свойств. TaskPluginTrait включает в себя стандартные методы для трансляции процедур (routines), улучшения форм задач и вызов подзадач.

advertiseRoutines()

Этот метод объявляет процедуры, поддерживаемые плагином. Он должен быть сопоставлен с событием onTaskOptionsList, позволяющим плагину объявлять свои процедуры. Метод уже определен в трейте, поэтому Вам не требуется определять его в вашем плагине.

enhanceTaskItemForm()

Этот метод расширяет форму задачи из XML-файла плагина, объявленного с помощью константы TASKS_MAP. Этот метод может быть сопоставлен с событием onContentPrepareForm. Этот метод уже определен в трейте, поэтому вам не требуется определять его в вашем плагине.

Вам нужно добавить имя формы в TASKS_MAP и константу и создать XML-форму в папке forms плагина с тем же именем.

standardRoutineHandler()

Метод сопоставляет стандартные процедуры задачи с методами класса. Вы можете добавить имя метода в константу TASKS_MAP и определить его в своем плагине. Выполняться метод будет при запуске задачи.

Этот метод должен быть сопоставлен с событием onExecuteTask. Ожидается, что эти методы будут принимать один аргумент (событие) и возвращать статус задачи в виде числа (integer).

logTask()

Этот метод добавляет сообщение в логи. Первый аргумент — это сообщение, а второй аргумент — приоритет: отладка, ошибка, предупреждение, уведомление, информация.

$this->logTask('Task is being executed', 'info');

Основной метод для выполнения задачи (doExample)

В примере выше это метод doExample.

use Joomla\Component\Scheduler\Administrator\Event\ExecuteTaskEvent; use Joomla\Component\Scheduler\Administrator\Task\Status;  /**  * Standard routine method for the get request routine.  *  * @param   ExecuteTaskEvent  $event  The onExecuteTask event  *  * @return integer  The exit code  *  * @since 4.1.0  * @throws Exception  */ private function doExample(ExecuteTaskEvent $event): int     {         // Code for Tasks                  return Status::OK;     }

В качестве параметра он принимает объект события onExecuteTask. Для выполнения задачи нам могут понадобится параметры, указанные в настройках плагина задачи. Получить параметры плагина можно с помощью метода $event->getArgument('params')

$id     = $event->getTaskId();  // Получаем параметры плагина, указанные в настройках  $params = $event->getArgument('params'); $url      = $params->url; $timeout  = $params->timeout; $auth     = (string) $params->auth ?? 0; $authType = (string) $params->authType ?? ''; $authKey  = (string) $params->authKey ?? '';

По завершении работы основного метода он должен вернуть статус выхода задачи.

Статусы выхода задачи в Joomla

На данный момент в Joomla 4 существует 12 возможных статусов завершения задачи, которым назначены числовые значения.

1. INVALID_EXIT = -2: используется, когда процедура возвращает неверный (не целочисленное, non-integer) статус завершения задачи.

2. NO_EXIT = -1: используется, когда процедура не возвращает статус завершения задачи..

3. RUNNING = 1: Используется при старте задачи. Это значение не должно быть статусом завершения задачи.

4. NO_LOCK = 2: Используется при невозможности получения pseudo-lock.

5. NO_RUN = 3: Используется при ошибке запуска задачи.

6. NO_RELEASE = 4: Используется при невозможности снять блокировку или обновить запись.

7. KNOCKOUT = 5: Используется, когда процедура «валится» из-за выкинутых исключений (Exception).

8. WILL_RESUME = 123: Используется, когда необходимо возобновить выполнение задачи. Используйте это для длительных задач, чтобы разделить их на более мелкие пакеты. Когда будет выполнен последний пакет, верните Status::OK.

9. TIMEOUT = 124: Используется в случае таймаута задачи.

10. NO_TASK = 125: Используется в случае, если задача не обнаружена.

11. NO_ROUTINE = 127: Используется в случае, если процедура задачи не обнаружена.

12. OK = 0: Успешное завершение задачи.

Пример из кода плагина Задача — GET-запрос

use Joomla\Component\Scheduler\Administrator\Task\Status as TaskStatus;  protected function makeGetRequest(ExecuteTaskEvent $event): int {  ...  try { $response = HttpFactory::getHttp($options)->get($url, $headers, $timeout); } catch (Exception $e) { $this->logTask(Text::sprintf('PLG_TASK_REQUESTS_TASK_GET_REQUEST_LOG_TIMEOUT'));  return TaskStatus::TIMEOUT; } ...  $this->logTask(Text::sprintf('PLG_TASK_REQUESTS_TASK_GET_REQUEST_LOG_RESPONSE', $responseCode));  if ($response->code !== 200) { return TaskStatus::KNOCKOUT; }  return TaskStatus::OK;  }

Принимаются пожелания по улучшению статьи и качества перевода 🙂

Так же полезные ресурсы

Ресурсы сообщества:

• форум русской поддержки Joomla.

• интернет-портал Joomla-сообщества.

• https://vc.ru/s/1146097-joomla — Сообщество Joomla на VC.

Telegram:

• чат сообщества «Joomla! по-русски».

• Joomla для профессионалов, разработчики Joomla.

• Новости о Joomla! и веб-разработке по-русски.

• вакансии и предложения работы по Joomla: фуллтайм, частичная занятость и разовые подработки. Размещение вакансий здесь.

• Англоязычный чат сообщества.