====== Интеграция и работа с очередью ======

В InstantCMS присутствует механизм "очередей". Это набор заданий, которые выполняются последовательно, согласно очередности и приоритета. После успешного выполнения задания, оно удаляется. У задания очереди есть состояния:

  * Ожидает выполнения;
  * Выполняется;
  * Ожидает повторного выполнения;
  * Завершено с ошибкой.

Очередь запускается по CRON при помощи системного [[manual:settings:scheduler|планировщика]]. За одно выполнение запускаются 20 задач очереди. Система очередей интегрирована в компоненты [[manual:components:messages|Личные сообщения]] и [[manual:components:subscriptions|Подписки]].

===== Работа с очередью =====

Вся работа с очередью заключается в большинстве случаев в постановке задания в очередь. Обслуживается это системным классом ''cmsQueue'', в котором все методы статические. Класс можно дополнить/переопределить, в нём используется [[http://php.net/manual/ru/language.oop5.late-static-bindings.php|позднее статическое связывание]].

==== Методы ====

Все методы класса являются статичными.

=== cmsQueue::pushOn ===

  pushOn(string  $queue, array  $data, integer  $priority = 1) : integer

Добавляет задание в очередь.

**Параметры**

^ Тип  ^ Имя ^ Описание ^
| string | $queue | Имя очереди. |
| array | $data | Основные данные очереди. |
| integer | $priority | Приоритет задания, по умолчанию 1. |

=== cmsQueue::pushOnLater ===

  pushOnLater(string  $queue, array  $data, integer  $priority = 1) : integer

Добавляет задачу в очередь с отсрочкой в секундах или по дате.

**Параметры**

^ Тип  ^ Имя ^ Описание ^
| mixed | $date | Количество секунд для смещения от текущего времени или полная дата. |
| string | $queue | Имя очереди. |
| array | $data | Основные данные очереди. |
| integer | $priority | Приоритет задания, по умолчанию 1. |

В обоих случаях в массиве $data передаются непосредственно полезные данные очереди, например:
<code php>
    cmsQueue::pushOn('email', array(
        'controller' => 'messages',
        'hook'       => 'queue_send_email',
        'params'     => array(
            $to, $letter, $is_nl2br_text
        )
    ));
</code>

Массив $data должен содержать ячейки:

  * **controller** - название контроллера (обязательно);
  * **hook** - название [[dev:controllers:hooks|хука]] контроллера (необязательно);
  * **action** - название [[dev:controllers:actions|экшена]] контроллера (необязательно);
  * **params** - параметры, передаваемые в хук или экшен (необязательно).

Должен быть передан либо **hook**, либо **action**. Если будет переданы оба параметра, вызовется сначала хук, потом экшен с одинаковыми параметрами **params**. Обратите внимание, что при выполнении задания в хук или экшен первым параметром всегда будет передаваться текущая попытка выполнения ''$attempts''.

===== Обработка очереди =====

Само выполнение задания очереди - это стандартный хук или экшен контроллера. При использовании хука, как метода исполнения задания очереди, нет необходимости его описывать в [[dev:controllers:hooks#манифест|файле манифеста]] контроллера.

Исполняющий хук или экшен задания **строго** может возвращать:

  * булево true - в этом случае движок будет считать, что задание выполнено успешно и удалит его из очереди;
  * булево false - задание выполнено, но будет запущено еще раз, пока не будет достигнуто максимальное кол-во перезапусков (по умолчанию 4);
  * любая строка, которая будет означать текст ошибки выполнения.

Выполнение каждого задания заключено в обработку [[http://php.net/manual/ru/language.exceptions.php|исключений]], поэтому все возможные ошибки выполнения отслеживаются и в случае их наличия, будут записаны в задание.

Пример реализации хука можно посмотреть [[https://github.com/instantsoft/icms2/blob/master/system/controllers/messages/hooks/queue_send_email.php|здесь]] или [[https://github.com/instantsoft/icms2/blob/master/system/controllers/subscriptions/hooks/send_letters.php|здесь]].

===== Интеграция списка заданий очереди в админке =====

Для удобной интеграции списка очереди, используемой в контроллере, необходимо в контроллере админки объявить следующее свойство (на примере контроллера подписок):
<code php>
public $queue = array(
    'queues'           => array('subscriptions'), // имена очередей, используемых в контроллере
    'queue_name'       => LANG_SBSCR_QUEUE_NAME,  // общее название этих очередей
    'use_queue_action' => true                    // флаг, разрешающий добавить раздел очередей в админку компонента
);
</code>

Для заданий очереди будут доступны действия удаления и перезапуска.

----

[[dev:integration|К оглавлению раздела "Интеграция"]]
----

[[dev:start|К оглавлению документации для разработчиков]]