Перейти к содержимому
Поиск
Разработка

Symfony Messenger: очереди PHP без фреймворка — 9 опытов и мастерская

Как вынести задачи PHP в фон: 9 опытов с настоящими очередями, повторами, ошибками и восстановлением. Мастерская, исходники Windows/Linux и практика VPS.

Александр Некрасов
Symfony Messenger: очереди PHP без фреймворка — 9 опытов и мастерская — обложка

Symfony Messenger: фоновые задачи в PHP без фреймворка

Пользователь нажимает «Сформировать отчёт», а сервер должен собрать данные, подготовить файл и сохранить результат. Если всё делать внутри HTTP-запроса, страница ждёт, соединение может оборваться, а повторное нажатие создаст ещё одну работу. Фоновая обработка разделяет принятие задания и его выполнение: приложение записывает намерение, отдельный процесс обрабатывает его, интерфейс показывает состояние по идентификатору.

Symfony Messenger помогает построить такую цепочку. Сообщение описывает задачу, обработчик выполняет действие, транспорт хранит сообщение до обработки, worker забирает доступную работу. Один и тот же обработчик можно вызвать сразу или через очередь. Здесь мы собираем самостоятельный PHP-проект: не устанавливаем целое Symfony-приложение и явно показываем, какие объекты связываются между собой.

В статье девять практических опытов: синхронный вызов, долговечная очередь SQLite, задержка, повтор после ошибки, очередь неудач и восстановление, идемпотентность, приоритет, ограничение worker и JSON-контракт. Мастерская показывает реальные результаты Windows и Linux. В архиве есть весь код, Composer lock, Dockerfile и инструкция размещения отдельного процесса на VPS.

Где очередь приносит пользу и что меняется в интерфейсе

Очередь пригодится для импорта большого CSV, подготовки архива документов, обработки изображений, построения отчёта за месяц и обмена с внешней системой. Общий признак: операция занимает заметное время или зависит от ненадёжного ресурса, а пользователь может получить результат позже. Например, кабинет сразу показывает номер заявки на отчёт, затем заменяет «В очереди» на «Готово» и предлагает ссылку на файл.

Не всякую операцию стоит переносить в фон. Проверку обязательного поля, расчёт небольшой суммы и подтверждение прав обычно нужно завершить до ответа. Нельзя показывать успешную оплату только потому, что сообщение поставлено в очередь. Разделите факт принятия задания, начало выполнения, успешный бизнес-эффект и доставку результата пользователю. Это разные состояния, для которых нужны понятные подписи.

Наш учебный обработчик создаёт запись отчёта в SQLite. Он не отправляет письма, не списывает деньги и не обращается к настоящему API. Такой небольшой эффект позволяет проверить весь путь сообщения и честно увидеть дубликат. После знакомства вы сможете заменить расчёт своим сервисом, сохранив отдельные проверки очереди, повторов и результата.

Message, Envelope, handler, transport и worker на одном примере

ReportJob содержит идентификатор задания, имя учебного клиента и режим опыта. Это данные, необходимые обработчику. Envelope оборачивает сообщение и добавляет служебные метки: например, задержку отправки или число повторов. Бизнес-класс не должен разбирать служебную структуру очереди, чтобы вычислить отчёт. Он получает ReportJob и возвращает наблюдаемый результат.

MessageBus пропускает Envelope через последовательность middleware. В асинхронной шине сначала стоит отправка в транспорт, затем обработка. Отправитель сохраняет задачу, а worker позднее передаёт полученное сообщение обратно в шину с признаком получения. Именно поэтому обработка не превращается в бесконечную повторную постановку. В синхронной шине нашего проекта есть только обработчик.

Транспорт отвечает за получение, подтверждение и отклонение сообщения. Worker управляет циклом обработки и событиями. Повторы и перенос в failed подключены отдельными слушателями, а не возникают из одного создания MessageBus. Эта явная сборка полезна для понимания компонента. Для общего справочника терминов и возможностей используйте документацию Messenger 7.4.

<?php
declare(strict_types=1);
namespace Workshop;

final readonly class ReportJob
{
    public function __construct(
        public string $id,
        public string $customer,
        public string $mode = 'normal',
    ) {
        if (!preg_match('/^[a-z0-9-]{1,40}$/D', $id)) {
            throw new \InvalidArgumentException('Invalid job id');
        }
        if (trim($customer) === '' || preg_match('/^.{1,100}$/usD', $customer) !== 1) {
            throw new \InvalidArgumentException('Customer is required, at most 100 characters');
        }
        if (!in_array($mode, ['normal', 'transient', 'permanent'], true)) {
            throw new \InvalidArgumentException('Unknown demonstration mode');
        }
    }
}

Версии, Composer и граница самостоятельного проекта

Проект проверен с Symfony Messenger 7.4.23, Doctrine Messenger 7.4.23 и Doctrine DBAL 4.6.0. Для нашего архива требуется PHP 8.3 или новее, PDO и pdo_sqlite. Полный набор зависимостей закреплён в composer.lock. Команда install воспроизводит этот набор; update пересчитывает зависимости и требует повторной проверки всех опытов, особенно транспортных метаданных и исключений.

В архиве нет FrameworkBundle. Поэтому привычные команды messenger:consume, YAML-конфигурация Symfony и автоматическое обнаружение атрибута AsMessageHandler здесь не работают сами по себе. Вместо этого есть собственная маленькая команда bin/console.php и Runtime с явной регистрацией одного обработчика. В существующем Symfony-приложении разумно использовать его штатную интеграцию и не копировать этот bootstrap буквально.

Важная техническая граница: низкоуровневый Connection из Doctrine bridge помечен internal. Здесь он используется для прозрачной учебной сборки с закреплёнными версиями и интеграционными проверками. Это не обещание стабильности конструктора на любое будущее обновление. Если установка зависимостей незнакома, начните с руководства по Composer.

{
  "name": "aen/symfony-messenger-workshop",
  "description": "Standalone Symfony Messenger workshop with isolated SQLite queues",
  "type": "project",
  "license": "MIT",
  "require": {
    "php": "^8.3",
    "ext-pdo": "*",
    "ext-pdo_sqlite": "*",
    "symfony/messenger": "~7.4.23",
    "symfony/doctrine-messenger": "~7.4.23",
    "symfony/event-dispatcher": "7.4.*",
    "symfony/dependency-injection": "7.4.*",
    "doctrine/dbal": "^4.4"
  },
  "autoload": {"psr-4": {"Workshop\\": "src/"}},
  "config": {"sort-packages": true, "allow-plugins": false}
}

Мини-мастерская: исследуйте результат по шагам

Выберите задачу и платформу. Для некоторых задач доступен дополнительный этап: у асинхронной обработки это отправитель, новый процесс и worker; у восстановления — ошибка, просмотр failed, повторная отправка и исправленный результат. Карточки очередей помогают сравнить, где сейчас лежит сообщение и появился ли отчёт. Переключение задачи сбрасывает просмотр событий, чтобы последовательности разных опытов не смешивались.

Кнопка следующего события постепенно раскрывает фактический журнал выбранного запуска. Можно показать всё сразу или начать заново, открыть полный JSON и сохранить его. Ниже находится просмотр исходников: выберите PHP-класс, CLI, Dockerfile или руководство VPS. Копирование сохраняет именно открытый файл; при недоступном буфере обмена остаётся скачивание и выделение текста.

Это интерактивный просмотр записей настоящего выполнения PHP, а не удалённый PHP-терминал. Кнопки на сайте не отправляют задания на хостинг. Для собственных данных скачайте проект и запустите его локально. В интерфейсе есть девять задач, двадцать одно представление этапов для каждой ОС и сведения о версиях. Времена запусков не используются для сравнения скорости Windows и Linux.

Windows: первый запуск из PowerShell

Распакуйте архив в отдельный каталог и откройте в нём терминал. Проверьте версию PHP, список расширений и путь к ini. PHP командной строки может отличаться от PHP локального веб-сервера: включённое расширение в одном окружении не гарантирует его наличия в другом. composer check-platform-reqs проверяет требования установленного набора на текущем PHP.

После установки выполните синхронный пример, затем поставьте другое задание в очередь. state до запуска worker покажет сообщение без готового отчёта. После consume состояние изменится. Повторяя эксперимент, используйте новый бизнес-идентификатор: прежний идентификатор намеренно защищён от второго создания отчёта. Иначе вы увидите duplicate-skipped, хотя запуск технически прошёл успешно.

По умолчанию база находится в .runtime/demo.sqlite. Это сохраняемое состояние между командами, а не временный массив процесса. Для чистого опыта задайте DEMO_DB с новым именем файла. Тестовый record.php создаёт собственные изолированные базы и не очищает вашу обычную demo.sqlite. Не удаляйте весь каталог проекта ради повторения одного примера.

php --version
php -m
composer install --no-plugins --no-scripts
composer check-platform-reqs
php bin/console.php sync sync-001 "Учебный клиент"
php bin/console.php enqueue report-001 "Учебный клиент"
php bin/console.php state
php bin/console.php consume
php bin/console.php state
php tools/record.php

Linux: тот же проект и изолированная проверка Docker

На Linux нужны CLI PHP подходящей версии, SQLite-расширение и Composer. Конкретные имена пакетов зависят от дистрибутива и подключённого репозитория. Проверьте php –version, php –ini и php -m до установки библиотек. Не смешивайте расширения от разных веток PHP и не ориентируйтесь только на версию, показанную веб-страницей phpinfo.

В Linux окружение удобно передать через export DEMO_DB или перед одной командой. Последовательность enqueue, consume и state сохраняется. Bash и PowerShell различаются синтаксисом переменных, поэтому в README приведены оба варианта. Сам PHP-код не выбирает отдельную бизнес-логику для каждой операционной системы: обе записи проверяются на одинаковый результат.

Dockerfile даёт воспроизводимую Linux-проверку с PHP 8.3.36 и PCNTL. Команды docker build -t messenger-workshop . и docker run –rm messenger-workshop собирают образ и выполняют девять опытов. Контейнер не публикует порты и не получает Docker socket. Для сохранения JSON снаружи в README показан bind mount только каталога записей, отдельно для Windows и Linux.

php --version
php -m
composer install --no-interaction --no-plugins --no-scripts
composer check-platform-reqs
export DEMO_DB="$PWD/.runtime/linux-demo.sqlite"
php bin/console.php enqueue report-001 'Учебный клиент'
php bin/console.php consume urgent,async 20
php bin/console.php state
unset DEMO_DB
php tools/record.php

Опыт 1. Синхронная обработка и значение HandledStamp

В первом опыте syncBus сразу передаёт ReportJob обработчику. После возврата dispatch в Envelope есть HandledStamp с результатом. В таблице reports уже лежит одна запись, а в async нет сообщения. Это полезная контрольная точка: мы видим работу бизнес-кода без ожидания отдельного процесса и без сохранения сообщения в транспорте.

Синхронная шина пригодится там, где результат нужен немедленно и операция короткая. Например, можно отделить вычисление предварительной стоимости от HTTP-контроллера и вызывать тот же сценарий из CLI. Но добавление MessageBus само по себе не делает вычисление параллельным и не сокращает его длительность. Исключение обработчика по-прежнему влияет на текущий вызов.

Сравните sync с enqueue во втором опыте. У асинхронного отправителя нет готового результата обработчика, потому что обработчик ещё не запускался. Нельзя переносить чтение HandledStamp из синхронной ветки в асинхронную и ожидать готовый отчёт. Для фоновой задачи нужен отдельный способ хранить и получать результат по бизнес-идентификатору.

php bin/console.php sync sync-001 'Учебный клиент'
php bin/console.php state

Опыт 2. Сообщение переживает завершение отправителя

После enqueue процесс заканчивается, но запись остаётся в SQLite. В мастерской откройте этап producer: handledInProducer равен false, reports пуст, async содержит одно сообщение. Затем выберите newProcess. Это результат отдельной команды state, которая заново открыла базу и увидела ту же очередь. Так проверяется сохранение между процессами, а не только наличие объекта в памяти.

Этап worker запускает настоящий Symfony Worker. После успешного обработчика транспорт получает подтверждение, сообщение исчезает из async, а reports содержит готовую запись. Получение из очереди и завершение обработки разделены. Именно между бизнес-эффектом и подтверждением может случиться сбой процесса, поэтому повторную доставку нужно учитывать заранее.

В прикладном API enqueue может соответствовать приёму заявки и ответу 202 с jobId. Отдельный маршрут состояния вернёт queued, running, completed или failed согласно вашей модели. В скачиваемом проекте такого HTTP API нет: команды позволяют сначала разобраться с очередью. Добавляя API, не превращайте произвольное имя PHP-класса из запроса пользователя в исполняемое сообщение.

php bin/console.php enqueue report-001 'Учебный клиент'
php bin/console.php state
php bin/console.php consume
php bin/console.php state

Как собраны транспорт и middleware

Runtime создаёт одно соединение Doctrine DBAL и три транспорта с разными queue_name: async, urgent и failed. Бизнес-таблицы и очередь находятся в одной учебной SQLite-базе. Каждый транспорт получает наш явный JSON serializer. Настройка busy_timeout позволяет ограниченно подождать освобождения SQLite-блокировки; она не превращает файловую базу в распределённую очередь.

HandlersLocator связывает ReportJob с ReportHandler. SendersLocator направляет обычную отправку в async. Для отдельных сообщений CLI добавляет TransportNamesStamp и выбирает urgent. Порядок middleware важен: сначала определяется отправка, затем возможна обработка. Если убрать отправляющий middleware из асинхронной шины, задание начнёт выполняться прямо в процессе отправителя.

В конструкторе оставлена автоматическая подготовка таблиц, чтобы архив запускался без отдельной миграции. Для реального сервиса вынесите подготовку схемы в управляемый этап релиза. Worker должен получать только необходимые права. Автоматическое создание таблиц при каждом старте удобно для мастерской, но не заменяет версионирование бизнес-схемы и контроль изменений на сервере.

foreach (['async','urgent','failed'] as $name) {
            $transport = new DoctrineTransport(new Connection(['queue_name'=>$name, 'auto_setup'=>false], $this->db), $this->serializer);
            $transport->setup();
            $this->transports[$name] = $transport;
        }
        $handlers = new HandleMessageMiddleware(new HandlersLocator([ReportJob::class=>[new ReportHandler($this->db, $repair)]]));
        $senders = new ServiceLocator(array_map(fn($transport)=>fn()=>$transport, $this->transports));
        $this->bus = new MessageBus([new SendMessageMiddleware(new SendersLocator([ReportJob::class=>['async']], $senders)), $handlers]);
        $this->syncBus = new MessageBus([$handlers]);

Опыт 3. Отложенная задача и граница точности времени

DelayStamp задаёт задержку, после которой сообщение может стать доступным обработчику. В нашем опыте это 1800 миллисекунд. Сразу после отправки тест обращается к транспорту и проверяет, что сообщений для обработки ещё нет. Затем отдельный worker ждёт доступность и создаёт отчёт. В мастерской видны requestedDelayMs, immediateMessages и фактический результат.

Практический пример — отложенная проверка статуса внешней операции, небольшая пауза перед повторной сверкой или учебное напоминание. Но доступность после задержки не означает исполнение точно в указанную миллисекунду. На итог влияют работающий worker, занятость очереди, опрос транспорта и планирование операционной системы. Для расписаний с календарём и часовыми поясами нужен отдельный слой планирования.

Обычный consume в архиве ограничен восемью секундами, чтобы локальная команда не зависала бесконечно. Если назначить задержку дольше этого времени, сообщение останется ждать следующего worker. Для постоянного ожидания есть watch с отдельными лимитами. Сравнивайте состояния очереди и результата, а не трактуйте любое завершение команды consume как доказательство обработки всех будущих сообщений.

php bin/console.php enqueue later-001 'Учебный клиент' normal 1800
php bin/console.php consume

Опыт 4. Два временных сбоя и успешная третья попытка

Режим transient специально выбрасывает RuntimeException на первых двух обращениях к одному заданию. Счётчик попыток хранится в базе и переживает новый PHP-процесс. Третья попытка создаёт отчёт. Это синтетическая причина ошибки, но доставка, обработчик, события и механизм повторов принадлежат настоящему Messenger. Мы не имитируем повтор простым циклом вокруг ручного вызова метода.

В мастерской раскройте события по одному. Сравните retried, failed с willRetry и заключительное handled. Два разрешённых повтора означают до трёх попыток: первоначальная плюс две дополнительные. Наличие события failed ещё не обязательно означает окончательное попадание в очередь неудач — смотрите willRetry и финальное состояние транспорта.

Для короткого опыта MultiplierRetryStrategy использует нулевую паузу. В production задайте осмысленный backoff, максимальную паузу и jitter, иначе недоступный сервис получит поток мгновенных запросов. Различайте временную сетевую ошибку, ограничение частоты и неверные данные. Один универсальный retry для любых исключений может увеличивать нагрузку и долго скрывать ошибку, которую нужно исправить вручную.

php bin/console.php enqueue retry-001 'Учебный клиент' transient
php bin/console.php consume

Повторы включаются слушателями, а не названием очереди

В самостоятельной сборке мы подключаем SendFailedMessageForRetryListener и SendFailedMessageToFailureTransportListener к EventDispatcher. Для каждой рабочей очереди задан отправитель повторов, стратегия и failed-транспорт. Worker получает этот dispatcher. Если просто создать Worker без такой конфигурации, поведение не станет автоматически совпадать с привычным Symfony-приложением.

Собственные слушатели журнала имеют низкий приоритет и читают событие после обработки основных слушателей. Поэтому поле willRetry отражает решение о повторе для текущего сбоя. Это хороший пример того, почему при диагностике важно знать не только название события, но и момент наблюдения. Слишком ранний снимок может показать ещё не принятое решение.

Служебный RedeliveryStamp переносит число повторов через транспорт. Наш serializer сохраняет этот счётчик явно. Если потерять его при сериализации, политика повторов может сбрасываться при каждой доставке. Проверка «два повтора и успех на третьей попытке» одновременно проверяет обработчик, listener, сериализацию метаданных и движение сообщения через очередь.

$strategies = new ServiceLocator(['async'=>fn()=>new MultiplierRetryStrategy(2, 0, 1, 0, 0), 'urgent'=>fn()=>new MultiplierRetryStrategy(2, 0, 1, 0, 0)]);
        $failures = new ServiceLocator(['async'=>fn()=>$this->transports['failed'], 'urgent'=>fn()=>$this->transports['failed']]);
        $dispatcher->addSubscriber(new SendFailedMessageForRetryListener($senders, $strategies, eventDispatcher:$dispatcher));
        $dispatcher->addSubscriber(new SendFailedMessageToFailureTransportListener($failures));
        $dispatcher->addSubscriber(new StopWorkerOnMessageLimitListener($limit));

Опыт 5. Постоянная ошибка попадает в failed

Режим permanent выбрасывает UnrecoverableMessageHandlingException. В нашем проекте такое сообщение не проходит обычные повторы: после первой неудачной обработки оно сохраняется в failed. В мастерской этап failure показывает одну попытку, отсутствие отчёта и одну запись в очереди неудач. Этап inspect выводит сохранённое сообщение, которое можно сопоставить с бизнес-идентификатором.

Очередь failed нужна для наблюдаемого разбирательства, а не для автоматического бесконечного прокручивания плохих задач. Причиной может быть некорректный источник, удалённая сущность, несовместимый формат или ошибка логики. Сначала установите причину и определите, допустимо ли повторное выполнение. Иногда правильное действие — исправить данные, иногда отменить задачу и сообщить пользователю.

Команда failed показывает первые двадцать сообщений. Это ограниченный учебный просмотр, а не административная панель с пагинацией, поиском и контролем доступа. Для рабочего сервиса сохраняйте безопасную диагностику, время, идентификатор и решение оператора. Полный payload может содержать персональные данные; его нельзя автоматически превращать в публичную страницу или безразмерный лог.

php bin/console.php enqueue bad-001 'Учебный клиент' permanent
php bin/console.php consume
php bin/console.php failed

Возврат из failed после исправления причины

Команда redrive ищет выбранный jobId среди первых двадцати неудач, отправляет свежий Envelope в async и удаляет прежнюю запись из failed. Бизнес-идентификатор сохраняется. В учебном permanent-сценарии переменная DEMO_REPAIR=1 отключает специально созданную ошибку: это переключатель опыта, а не способ исправления внешнего сервиса или автоматический ремонт настоящих данных.

В Windows задайте $env:DEMO_REPAIR = ‘1’, выполните consume и удалите переменную командой Remove-Item Env:DEMO_REPAIR. В Bash можно передать DEMO_REPAIR=1 перед единственным запуском PHP. В мастерской сравните redrive и repaired: после переноса отчёта ещё нет, после исправленной обработки появляется одна бизнес-запись, обе очереди пусты.

Перенос send → reject здесь не атомарный. Если процесс оборвётся между этими действиями, возможен дубликат. Поэтому redrive не отменяет требования к идемпотентности обработчика. Для серьёзной административной операции также нужны права доступа, журнал действий и защита от одновременного повторного запуска. Массовое возвращение всего failed без анализа причин обычно только повторяет первоначальную аварию.

php bin/console.php redrive bad-001
DEMO_REPAIR=1 php bin/console.php consume

Опыт 6. Две доставки создают один отчёт

Идемпотентность означает, что повторное выполнение одной бизнес-операции не создаёт второй нежелательный эффект. В опыте один и тот же идентификатор ставится в очередь дважды. Worker обрабатывает два сообщения, но таблица reports получает одну строку. Первое событие содержит effect=created, второе — duplicate-skipped. Число доставок и число бизнес-результатов намеренно различаются.

Защита находится в базе: job_id — первичный ключ, а вставка выполняется в транзакции через INSERT OR IGNORE. Проверка наличия записи отдельным SELECT без ограничения уникальности не дала бы такой же защиты при конкуренции. Вместе с тем этот пример покрывает только локальную запись отчёта. Он не доказывает отсутствие повторной отправки письма или платежа во внешнем сервисе.

Идентификатор должен описывать одну логическую операцию и оставаться прежним при повторе. Если каждый retry получает новый UUID, уникальное ограничение перестаёт помогать. Если один ID повторно используется для другого содержимого, наш пример оставит первый отчёт. В рабочей модели дополнительно проверяют совпадение значимых параметров или хеша запроса и явно отклоняют конфликт.

<?php
declare(strict_types=1);
namespace Workshop;

use Doctrine\DBAL\Connection;
use Symfony\Component\Messenger\Exception\UnrecoverableMessageHandlingException;

final class ReportHandler
{
    public function __construct(private Connection $db, private bool $repair = false) {}

    public function __invoke(ReportJob $job): array
    {
        $this->db->executeStatement('INSERT INTO attempts(job_id, amount) VALUES (?,1) ON CONFLICT(job_id) DO UPDATE SET amount=amount+1', [$job->id]);
        $attempt = (int)$this->db->fetchOne('SELECT amount FROM attempts WHERE job_id=?', [$job->id]);
        // Explicit synthetic failures: no external email, payment or HTTP call.
        if ($job->mode === 'transient' && $attempt <= 2) {
            throw new \RuntimeException('Synthetic temporary service failure');
        }
        if ($job->mode === 'permanent' && !$this->repair) {
            throw new UnrecoverableMessageHandlingException('Synthetic invalid report source');
        }
        return $this->db->transactional(function (Connection $db) use ($job, $attempt): array {
            $created = $db->executeStatement('INSERT OR IGNORE INTO reports(job_id, customer, total_kopecks) VALUES (?,?,?)', [$job->id, $job->customer, 37500]);
            return ['jobId'=>$job->id, 'attempt'=>$attempt, 'effect'=>$created ? 'created' : 'duplicate-skipped', 'totalKopecks'=>37500];
        });
    }
}

Транзакция, подтверждение и внешний API

Представьте, что запись отчёта уже зафиксирована, а процесс завершился до подтверждения сообщения. После повторной доставки обработчик снова увидит тот же jobId. Именно для этого нужна защита бизнес-эффекта. Наличие очереди не создаёт универсальную гарантию «ровно один раз» для всех действий, особенно когда в операции участвуют разные базы и внешние сервисы.

Транзакция Doctrine объединяет локальные изменения одной базы. Она не откатывает уже отправленное HTTP-письмо и не отменяет внешний платёж. Для внешнего API изучите его idempotency key и способ узнать состояние операции после неопределённого сетевого ответа. Иногда нужен outbox: запись намерения рядом с бизнес-изменением, затем отдельная доставка. В данном архиве outbox не реализован.

Не держите SQLite-транзакцию открытой во время долгого сетевого запроса без ясной причины. Это увеличивает время блокировок и усложняет восстановление. Сначала определите границы локальной атомарности и внешнего эффекта, затем выберите порядок действий. Механика transactional и обработка исключений описаны в официальной документации Doctrine DBAL.

Опыт 7. Приоритетная и обычная очередь

В опыте сначала отправляется normal-001 в async, затем urgent-001 в urgent. Worker получает список urgent,async. Итоговый журнал показывает urgent-001 первым, хотя обычная задача была поставлена раньше. Так можно разделить срочную служебную операцию и тяжёлый фоновый импорт, чтобы один поток работы не определял порядок для всех задач приложения.

Приоритет не означает прерывание уже запущенного обработчика. Если worker выполняет большой отчёт, поступившее срочное сообщение будет ждать доступного процесса. При постоянном потоке urgent обычная очередь может долго не получать внимания. Для предсказуемого сервиса часто выделяют отдельные workers или доли ресурсов, а не полагаются только на порядок имён.

Не позволяйте любому клиенту API самостоятельно объявлять каждую задачу срочной. Приоритет — часть правил приложения. В CLI разрешены только async и urgent; failed нельзя передать как рабочую очередь consume. Это помогает не превращать хранилище неудач в бесконтрольный цикл повторов. В мастерской сравните порядок отправки с порядком handled в журнале.

php bin/console.php enqueue normal-001
php bin/console.php enqueue urgent-001 'Учебный клиент' normal 0 urgent
php bin/console.php consume urgent,async

Опыт 8. Ограниченный worker и следующий процесс

В восьмом опыте в очередь попадают две задачи. Первый worker запускается с лимитом один, обрабатывает одну задачу и выходит. В его результате остаётся одно сообщение async и один отчёт. Второй отдельный процесс обрабатывает остаток. Это подтверждает, что завершение worker по лимиту не очищает очередь и не требует удерживать все задания в памяти одного процесса.

Ограничения помогают регулярно обновлять долгоживущий процесс и снижать накопление состояния. Но лимит должен контролировать supervisor: если worker штатно завершился и никто не запустил следующий, очередь просто остановится. В архиве обычный режим также завершает работу при пустых очередях или после восьми секунд. Он удобен для опыта, а не для постоянного обслуживания.

Режим consume urgent,async 100 watch ждёт новые сообщения, но ограничен ста обработками и одним часом. Watch не является daemonize и не обеспечивает автоматический перезапуск. На Linux эту обязанность возьмёт systemd. При расчёте лимитов учитывайте и ошибки: большое количество повторов может израсходовать бюджет процесса быстрее, чем ожидается по числу уникальных бизнес-задач.

php bin/console.php consume async 1
php bin/console.php state
php bin/console.php consume async 1

Опыт 9. JSON-контракт и отказ от неизвестного сообщения

Serializer принимает только report.v1 и явно перечисленные поля. Версия в body должна быть целым числом 1, а id, customer и mode — строками, которые дополнительно проверяет ReportJob. Размер тела ограничен 4096 байтами, глубина JSON — шестнадцатью. Это небольшой понятный контракт для одного учебного сообщения, а не универсальная сериализация любого PHP-объекта.

В опыте проверяется успешное кодирование и восстановление, затем три отрицательных случая: сломанный JSON, неизвестный type и неверная схема. Все три получают MessageDecodingFailedException. Важно видеть именно отказ, а не пустой объект, который обработчик позже случайно примет за корректную задачу. Ни имя произвольного PHP-класса, ни вызов unserialize из входных данных здесь не используются.

Служебные headers сохраняют число повторов и исходную очередь failed. Произвольные Messenger stamps этот serializer не переносит. При добавлении трассировки, новой метки или другого типа сообщения контракт нужно расширить и проверить. Само использование JSON не заменяет аутентификацию отправителя, правила доступа к транспорту и проверку того, что клиент имеет право создать конкретное задание.

<?php
declare(strict_types=1);
namespace Workshop;

use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\Exception\MessageDecodingFailedException;
use Symfony\Component\Messenger\Stamp\RedeliveryStamp;
use Symfony\Component\Messenger\Stamp\SentToFailureTransportStamp;
use Symfony\Component\Messenger\Transport\Serialization\SerializerInterface;

/** Explicit versioned contract for this single message; never unserialize input. */
final class JsonEnvelopeSerializer implements SerializerInterface
{
    public function encode(Envelope $envelope): array
    {
        $job = $envelope->getMessage();
        if (!$job instanceof ReportJob) { throw new \InvalidArgumentException('Unsupported message'); }
        $body = json_encode(['v'=>1, 'id'=>$job->id, 'customer'=>$job->customer, 'mode'=>$job->mode], JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
        $headers = ['type'=>'report.v1', 'retry'=>RedeliveryStamp::getRetryCountFromEnvelope($envelope)];
        if ($failure = $envelope->last(SentToFailureTransportStamp::class)) {
            $headers['failureOrigin'] = $failure->getOriginalReceiverName();
        }
        return ['body'=>$body, 'headers'=>$headers];
    }

    public function decode(array $encodedEnvelope): Envelope
    {
        try {
            $body = $encodedEnvelope['body'] ?? null;
            $headers = $encodedEnvelope['headers'] ?? [];
            if (!is_string($body) || strlen($body) > 4096 || ($headers['type'] ?? null) !== 'report.v1') {
                throw new \InvalidArgumentException('Unsupported type or body size');
            }
            $data = json_decode($body, true, 16, JSON_THROW_ON_ERROR);
            if (!is_array($data) || ($data['v'] ?? null) !== 1 || !is_string($data['id'] ?? null) || !is_string($data['customer'] ?? null) || !is_string($data['mode'] ?? null)) {
                throw new \InvalidArgumentException('Expected report.v1 fields');
            }
            $retry = $headers['retry'] ?? 0;
            if (!is_int($retry) || $retry < 0 || $retry > 10) { throw new \InvalidArgumentException('Invalid retry metadata'); }
            $envelope = new Envelope(new ReportJob($data['id'], $data['customer'], $data['mode']), [new RedeliveryStamp($retry)]);
            if (isset($headers['failureOrigin'])) {
                if (!in_array($headers['failureOrigin'], ['async','urgent'], true)) { throw new \InvalidArgumentException('Invalid failure origin'); }
                $envelope = $envelope->with(new SentToFailureTransportStamp($headers['failureOrigin']));
            }
            return $envelope;
        } catch (\Throwable $error) {
            throw new MessageDecodingFailedException('Invalid report envelope: '.$error->getMessage(), 0, $error);
        }
    }
}

Изменение сообщений между релизами

Очередь может пережить обновление приложения. Сообщение, созданное старым отправителем, попадёт к новому worker через минуту или после восстановления сервера. Поэтому переименование поля, удаление класса и изменение смысла значения требуют плана совместимости. В нашем проекте report.v1 и поле v позволяют явно узнать поддерживаемый контракт, а не угадывать его по наличию случайных ключей.

При небольшом расширении можно сохранить чтение старой формы и добавить значение по умолчанию для нового необязательного поля. При несовместимом изменении заведите новую версию и предусмотрите обработку старых сообщений до их исчерпания. Сначала обновляйте потребителей так, чтобы они понимали обе формы, затем отправителей. Конкретный порядок зависит от модели развёртывания и доступного отката.

Не отправляйте в очередь целую ORM-сущность вместе с устаревшим состоянием и зависимостями. Часто достаточно идентификатора и неизменяемых параметров операции; актуальные данные обработчик получает отдельно и проверяет их существование. Для отчёта за фиксированный период, напротив, может понадобиться закреплённый снимок условий. Решение определяется смыслом задачи, а не удобством автоматического сериализатора.

Linux/VPS: код отдельно, состояние отдельно

Для размещения создайте отдельного системного пользователя и каталог состояния вне document root. Код релиза находится в /opt/messenger-demo/releases, постоянная SQLite-база — в /var/lib/messenger-demo. Worker читает код и пишет только туда, где это действительно нужно. Нельзя публиковать весь распакованный проект корнем сайта: база очереди и служебные файлы не предназначены для посетителей.

Устанавливайте зависимости под пользователем развёртывания, проверяйте требования PHP и сначала запускайте команду state от имени worker. В учебном Runtime она также подготовит таблицы. Это позволяет обнаружить неверный путь и права до включения службы. Для первого развёртывания создаётся ссылка current на проверенный релиз; при последующих обновлениях переключение выполняется отдельным управляемым действием.

В docs/linux-vps.md приведена полная последовательность, включая пользователя, каталоги, Composer, контроль состояния и резервную копию. Она является шаблоном для собственного сервера. В наших проверках реально выполнены Windows CLI и Linux Docker; отдельный VPS, его пакеты, права и systemd на этом стенде не разворачивались. Эти этапы нужно проверить на целевом хосте.

sudo useradd --system --home /opt/messenger-demo --shell /usr/sbin/nologin messenger-demo
sudo install -d -o root -g root -m 0755 /opt/messenger-demo/releases
sudo install -d -o messenger-demo -g messenger-demo -m 0700 /var/lib/messenger-demo

Systemd: запуск, перезапуск и мягкое завершение

Unit в архиве запускает watch-worker от отдельного пользователя. Restart=always возвращает процесс после штатного достижения лимита, RestartSec ограничивает частоту перезапусков. WorkingDirectory и DEMO_DB заданы явно, поэтому служба не зависит от текущего SSH-каталога. Защитные параметры ограничивают доступную запись каталогом состояния; проверьте их совместимость с добавленными вами обработчиками.

На Linux PCNTL перехватывает SIGTERM и SIGINT и просит Worker завершиться. Длительность TimeoutStopSec должна учитывать реальную задачу. Если процесс принудительно убит после эффекта и до ack, повторная доставка остаётся возможной. Настройка redeliver_timeout транспорта тоже должна соответствовать длительности обработки. Не выбирайте эти значения только по скорости короткого учебного отчёта.

В тесте отдельный Linux worker действительно запущен в watch, получил SIGTERM и завершился с кодом ноль. Проверка относится к ожидающему worker; она не доказывает завершение любого долгого внешнего запроса. Windows Ctrl+C может иметь другую семантику. PCNTL ориентирован на Unix-процессы, подробнее — в справочнике PHP.

[Unit]
Description=Standalone Messenger report worker
After=network.target

[Service]
Type=simple
User=messenger-demo
Group=messenger-demo
WorkingDirectory=/opt/messenger-demo/current
Environment=DEMO_DB=/var/lib/messenger-demo/queue.sqlite
ExecStart=/usr/bin/php /opt/messenger-demo/current/bin/console.php consume urgent,async 100 watch
Restart=always
RestartSec=5
KillSignal=SIGTERM
TimeoutStopSec=60
UMask=0077
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/messenger-demo

[Install]
WantedBy=multi-user.target

Наблюдаемость: очередь, возраст задания и журнал

Одного счётчика pending недостаточно. Десять свежих задач и десять задач, зависших со вчерашнего дня, означают разные ситуации. В рабочем сервисе полезно измерять возраст старейшего сообщения, длительность обработчика, количество повторов, размер failed и число завершений за период. Отдельно следите за живым worker: пустая очередь не подтверждает его способность обработать новую задачу.

В этой мастерской JSON событий выводится после завершения команды. Для постоянно работающего процесса нужен потоковый структурированный журнал, чтобы проблему было видно до конца часового цикла. Включайте безопасный jobId, тип операции, очередь, номер попытки и категорию ошибки. Не записывайте целиком пароли, токены и документы только ради удобной диагностики.

Для прикладного журнала подойдёт Monolog, уже разобранный на сайте. Свяжите записи отправителя и worker одним идентификатором. Добавьте проверку контрольного задания после релиза: оно должно пройти очередь и создать ожидаемый результат. Один успешный запуск systemctl без проверки бизнес-эффекта не подтверждает здоровье всей цепочки.

SQLite: возможности, резервная копия и пределы

SQLite удобен для самостоятельного знакомства: не нужен отдельный сервер базы, а очередь и результаты можно исследовать одним инструментом. Файл сохраняет состояние между процессами. Но конкурирующая запись, блокировки, длительность транзакций и размещение файла становятся частью эксплуатационной модели. Не переносите выводы одного локального опыта на несколько серверов с общей сетевой папкой.

Для резервной копии работающей базы используйте подходящий SQLite backup-механизм, затем отдельно проверьте integrity_check и восстановление. Простое копирование одного файла во время записи, особенно при journal или WAL, не считается полной проверенной копией. Архив очереди может содержать данные клиентов; доступ, срок хранения и удаление должны быть такими же продуманными, как у основной базы.

В большом PHP-мануале сайта есть отдельные главы PDO_SQLITE: локальная очередь и SQLite3: локальная база, запросы и транзакции. Они помогут разобрать запросы и подготовленные выражения. При росте нагрузки оценивайте PostgreSQL, Redis или AMQP transport по реальным требованиям. Смена транспорта не отменяет retry, ack, совместимость сообщений и защиту от повторного эффекта.

sudo -u messenger-demo sqlite3 /var/lib/messenger-demo/queue.sqlite \
  ".backup '/var/lib/messenger-demo/queue-backup.sqlite'"
sudo -u messenger-demo sqlite3 /var/lib/messenger-demo/queue-backup.sqlite 'PRAGMA integrity_check;'

Типичные ошибки и понятная диагностика

Если enqueue прошёл, а отчёта нет, сначала проверьте, запускался ли worker и смотрит ли он в тот же DEMO_DB. Разные рабочие каталоги и переменные окружения часто создают две независимые SQLite-базы. Затем сравните имя очереди, задержку, лимиты и failed. Не запускайте бесконечно новые копии процесса, пока не выяснено, где лежит конкретный jobId.

Ошибка could not find driver указывает на расширение текущего PHP, а не на отсутствие Composer-пакета. Permission denied требует проверки владельца каталога состояния. Database is locked заставляет посмотреть длительность транзакций и параллельную запись. Не лечите все три проблемы chmod 777 или снятием ограничений сразу: это разные причины с разными исправлениями.

Если отчёт создан, но задача снова приходит, проверьте подтверждение, аварийный выход и время повторной доставки. Если повторы никогда не заканчиваются, проверьте сохранение RedeliveryStamp и выбранную стратегию. Если после обновления не читается JSON, сравните контракт старого сообщения с новым decoder. В каждом случае полезнее сохранить минимальный воспроизводимый пример и безопасный идентификатор, чем скрыть исключение общим успешным ответом.

Что проверено и как воспроизвести результаты

На Windows с PHP 8.3.33 и Linux с PHP 8.3.36 выполнено по сорок три проверки. Они подтверждают немедленную обработку, сохранение очереди между отдельными процессами, отсутствие ранней выдачи задержанного сообщения, два повтора, failed и восстановление, один эффект при двух доставках, приоритет и продолжение после лимита. Отдельно проверены корректный JSON и три ожидаемых отказа decoder.

Обе платформы создали девять записей. При сравнении бизнес-результаты совпадают; исключается только измеренное elapsedMs. Файлы содержат версии PHP и библиотек, команды, результаты и SHA-256 исходников. Хеш связывает запись с конкретным кодом, но не является цифровой подписью или доказательством производительности. После изменения файла сначала обновите просмотр исходников, затем повторите выполнение на обеих платформах.

Проверка интерфейса отдельно проходит все сорок два представления этапов, точность девятнадцати файлов, последовательность событий, отказ загрузки и восстановление. Это не заменяет просмотр адаптивной страницы в браузере. Для своей модификации добавляйте проверки наблюдаемого поведения: что осталось в очереди, сколько бизнес-записей появилось и какой отказ ожидается. Количество зелёных строк само по себе не описывает эти границы.

python tools/prepare-public.py
php tools/record.php
docker build -t messenger-workshop .
docker run --rm messenger-workshop

Исходники и следующий шаг для своего приложения

Архив содержит MessageBus и Worker, три транспорта, обработчик, явный JSON serializer, CLI, Composer lock, Dockerfile, девять записанных сценариев для каждой ОС и статическую мастерскую. Есть README с PowerShell и Bash, руководство Linux/VPS и systemd unit. Авторские файлы доступны по MIT, сторонние зависимости сохраняют собственные лицензии. В публичной мастерской PHP-код не исполняется.

Для первого полезного расширения замените запись учебного отчёта созданием небольшого файла в отдельном рабочем каталоге. Сохраните стабильный jobId, определите поведение при существующем файле и добавьте проверку сбоя между созданием и подтверждением. Затем подключите безопасный HTTP endpoint принятия задания и отдельный маршрут состояния. Интерфейс должен различать «принято» и «готово» и корректно показывать окончательную ошибку.

Основные источники: руководство Messenger 7.4, исходники Messenger 7.4.23, Doctrine bridge той же версии. Для сравнения подхода в Node.js есть материал о BullMQ. Выбирайте инструмент под стек и требования операции, сохраняя понятные контракты, наблюдаемый результат и воспроизводимые проверки.