Durable Workflow - безкоштовний пакет з відкритим кодом (MIT) для довгих багатокрокових фонових процесів у Laravel, які мають зберігати прогрес між рестартами воркерів. Його автор - Річард Макденіел (Richard McDaniel), а раніше пакет був відомий як Laravel Workflow: старий репозиторій laravel-workflow/laravel-workflow тепер веде на новий. Laravel News якраз розібрав пакет, а 17 листопада вийшов реліз 2.29.0.
Проблема знайома багатьом. Процес "згенеруй звіт - завантаж у сховище - надішли листа" зазвичай складають з ланцюжка джобів і кількох прапорців у таблиці. Коли воркер падає після завантаження, незрозуміло, що вже зроблено: генерувати звіт знову, завантажувати вдруге чи одразу слати лист. Durable Workflow бере підхід, відомий за Temporal, але запускає його всередині звичайного Laravel-застосунку - на ваших базі даних, чергах і кеші.
Workflow координує, activity виконують
Пакет ділить процес на дві ролі. Workflow описує порядок кроків і рішення між ними. Activity - це сама робота: згенерувати файл, викликати зовнішній API, записати щось у базу.
Результат кожної activity потрапляє в історію виконання. Коли workflow відновлюється після рестарту, пакет знову проганяє його PHP-код, але activity, чий результат уже записаний, вдруге не виконується - береться збережене значення. Документація формулює це як "відтворення - це не повтор": відтворення перебудовує стан з історії, а не запускає побічні ефекти заново.
Звіт у три кроки
Класи генеруються artisan-командами з прапорцем --v2 (вони потрапляють у app/Workflows):
php artisan make:workflow ReportWorkflow --v2
php artisan make:activity GenerateReport --v2
Workflow - звичайний PHP-код, де кожен крок викликається через activity():
use Workflow\V2\Workflow;
use function Workflow\V2\activity;
final class ReportWorkflow extends Workflow
{
public function handle(int $reportId): string
{
$path = activity(GenerateReport::class, $reportId);
$url = activity(UploadReport::class, $reportId, $path);
activity(NotifyReportReady::class, $reportId, $url);
return $url;
}
}
Кожна activity наслідує Workflow\V2\Activity і має метод handle(). Запуск із застосунку повертається одразу, а виконує процес воркер черги:
use Workflow\V2\WorkflowStub;
WorkflowStub::make(ReportWorkflow::class)->start($reportId);
Якщо воркер впаде після UploadReport, при відновленні генерація і завантаження візьмуться з історії, і процес перейде до листа.
Вимоги: асинхронна черга і кеш з locks
Поточний 2.x потребує PHP 8.2+ і Laravel 12.72+ або 13.41+ (для Laravel 13 - PHP 8.3+). Встановлення стандартне, міграції пакет підвантажує сам:
composer require durable-workflow/workflow:2.29.0
php artisan migrate
Що потрібно від інфраструктури, за документацією:
- будь-який асинхронний драйвер черги Laravel - database, Redis, Amazon SQS, Beanstalkd; драйвер
sync не підтримується;
- кеш-драйвер, що підтримує locks;
- запущений
php artisan queue:work або Horizon, а для паралельного виконання кроків - більше одного воркера.
Реліз 2.29.0 додає сім міграцій (лише нові таблиці й nullable-колонки, наявні рядки не переписуються), тож php artisan migrate після оновлення обов'язковий. Частина нових можливостей, як-от compensation scopes, позначена експериментальною, без гарантій зворотної сумісності.
Детермінованість: чому в workflow не можна now()
Це головне правило пакета, і на ньому найчастіше спотикаються. Оскільки код workflow відтворюється при кожному відновленні, він мусить ухвалювати ті самі рішення на тих самих записаних даних. Carbon::now() при відтворенні через годину поверне інший час, random_int() - інше число, запит до бази - інший рядок, і workflow піде іншою гілкою, ніж уперше. Обмеження workflow прямо перелічують, чого уникати:
- замість
Carbon::now() чи now() - Workflow::now() або хелпер Workflow\V2\now(), що повертає час останньої записаної події;
- замість
Auth::user() - передати користувача як вхідні дані при старті;
- запити до БД і HTTP-виклики - лише в activity;
- випадкові значення - через
sideEffect(), який виконує замикання один раз і записує результат.
$token = sideEffect(fn () => random_int(1000, 9999));
sideEffect() не підходить для того, що може впасти: замикання не повторюється, тож HTTP-запит у ньому - погана ідея. Для такого є activity. Пакет ще й сканує класи workflow при завантаженні застосунку і попереджає про Carbon::now(), DB::, Http::, random_int() тощо. У CI варто поставити DW_V2_GUARDRAILS_BOOT=throw, щоб збірка падала. Але скан лексичний і виклик через власний сервіс не помітить.
Друга половина контракту стосується activity: вони виконуються щонайменше один раз (at-least-once). Якщо воркер встиг завантажити файл, але впав до запису результату, activity запуститься знову. Тому activity мають бути безпечними для повтору: стабільний ключ в об'єктному сховищі, upsert, ключ ідемпотентності для платіжного API (документація радить $this->activityId()). І ще деталь: у v2 activity за замовчуванням має одну спробу ($tries = 1), повтори після винятку треба ввімкнути самому через $tries і backoff().
Сигнали: чекати на людину
Workflow може зупинитися й чекати на зовнішню подію - підтвердження менеджера, вебхук від платіжної системи. Для цього є сигнали: назва оголошується атрибутом #[Signal], а в коді workflow викликається await():
#[Signal('approved-by', [['name' => 'approvedBy', 'type' => 'string']])]
final class OrderApprovalWorkflow extends Workflow
{
public function handle(): array
{
$approvedBy = await('approved-by', timeout: days(2));
return ['approved_by' => $approvedBy];
}
}
Сигнал надсилається з контролера через WorkflowStub::load('order-123')->attemptSignalWithArguments('approved-by', [...]). Якщо за два дні сигналу немає, await() поверне null. Важливо: аргумент сигналу - це просто дані. Автентифікацію й авторизацію того, хто натиснув "Підтвердити", робить ваш застосунок до надсилання сигналу. Окремо є довговічні таймери timer(), які переживають рестарти.
А як щодо Cloud
У проєкту є платний керований Durable Workflow Cloud і окремий сервер для воркерів на інших мовах. Laravel-пакет їх не потребує: він повністю працює на вашій інфраструктурі, і платите ви лише за неї.
Пакет чи Bus::chain()
Для одного фонового завдання або короткого ланцюжка, де кожен крок легко повторити, вистачить вбудованих Bus::chain() і Bus::batch(). Вони простіші, не вимагають окремих таблиць і правил детермінованості.
Durable Workflow має сенс, коли:
- кроків багато, і повторне виконання вже зробленого дороге або шкідливе (платежі, листи клієнтам);
- процес триває години чи дні і чекає на людину або зовнішню систему;
- потрібна гілкова логіка між кроками, а не лише послідовність;
- хочеться бачити історію кожного запуску - для цього є UI Waterline.
Перш ніж переносити наявні процеси, врахуйте: зміна коду workflow, поки старі запуски ще не завершились, вимагає версіонування, бо старі запуски відтворюються на новому коді. Почати варто з одного нового процесу, а не з міграції всіх ланцюжків одразу.