---
title: "Durable Workflow: довгі фонові процеси в Laravel, які переживають падіння воркера"
url: https://laravelukraine.com/blog/durable-workflow-dovgi-fonovi-procesi-v-laravel-iaki-perezivaiut-padinnia-vorkera
date: 2026-11-19
---

# Durable Workflow: довгі фонові процеси в Laravel, які переживають падіння воркера

[Durable Workflow](https://github.com/durable-workflow/workflow) - безкоштовний пакет з відкритим кодом (MIT) для довгих багатокрокових фонових процесів у Laravel, які мають зберігати прогрес між рестартами воркерів. Його автор - Річард Макденіел (Richard McDaniel), а раніше пакет був відомий як Laravel Workflow: старий репозиторій `laravel-workflow/laravel-workflow` тепер веде на новий. [Laravel News](https://laravel-news.com/durable-workflow-laravel) якраз розібрав пакет, а 17 листопада вийшов [реліз 2.29.0](https://github.com/durable-workflow/workflow/releases/tag/2.29.0).

Проблема знайома багатьом. Процес "згенеруй звіт - завантаж у сховище - надішли листа" зазвичай складають з ланцюжка джобів і кількох прапорців у таблиці. Коли воркер падає після завантаження, незрозуміло, що вже зроблено: генерувати звіт знову, завантажувати вдруге чи одразу слати лист. Durable Workflow бере підхід, відомий за Temporal, але запускає його всередині звичайного Laravel-застосунку - на ваших базі даних, чергах і кеші.

### Workflow координує, activity виконують

Пакет ділить процес на дві ролі. Workflow описує порядок кроків і рішення між ними. Activity - це сама робота: згенерувати файл, викликати зовнішній API, записати щось у базу.

Результат кожної activity потрапляє в історію виконання. Коли workflow відновлюється після рестарту, пакет знову проганяє його PHP-код, але activity, чий результат уже записаний, вдруге не виконується - береться збережене значення. Документація формулює це як "відтворення - це не повтор": [відтворення](https://durable-workflow.com/docs/constraints/execution-guarantees/) перебудовує стан з історії, а не запускає побічні ефекти заново.

### Звіт у три кроки

Класи генеруються artisan-командами з прапорцем `--v2` (вони потрапляють у `app/Workflows`):

```bash
  php artisan make:workflow ReportWorkflow --v2
  php artisan make:activity GenerateReport --v2
```

Workflow - звичайний PHP-код, де кожен крок викликається через `activity()`:

```php
  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()`. Запуск із застосунку повертається одразу, а виконує процес воркер черги:

```php
  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+). Встановлення стандартне, міграції пакет підвантажує сам:

```bash
  composer require durable-workflow/workflow:2.29.0
  php artisan migrate
```

Що потрібно від інфраструктури, за [документацією](https://durable-workflow.com/docs/installation/):

- будь-який асинхронний драйвер черги 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](https://durable-workflow.com/docs/constraints/workflow-constraints/) прямо перелічують, чого уникати:

- замість `Carbon::now()` чи `now()` - `Workflow::now()` або хелпер `Workflow\V2\now()`, що повертає час останньої записаної події;
- замість `Auth::user()` - передати користувача як вхідні дані при старті;
- запити до БД і HTTP-виклики - лише в activity;
- випадкові значення - через `sideEffect()`, який виконує замикання один раз і записує результат.

```php
  $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 може зупинитися й чекати на зовнішню подію - підтвердження менеджера, вебхук від платіжної системи. Для цього є [сигнали](https://durable-workflow.com/docs/features/signals/): назва оголошується атрибутом `#[Signal]`, а в коді workflow викликається `await()`:

```php
  #[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`. Важливо: аргумент сигналу - це просто дані. Автентифікацію й авторизацію того, хто натиснув "Підтвердити", робить ваш застосунок до надсилання сигналу. Окремо є [довговічні таймери](https://durable-workflow.com/docs/features/timers/) `timer()`, які переживають рестарти.

### А як щодо Cloud

У проєкту є платний керований Durable Workflow Cloud і окремий сервер для воркерів на інших мовах. Laravel-пакет їх не потребує: він повністю працює на вашій інфраструктурі, і платите ви лише за неї.

### Пакет чи Bus::chain()

Для одного фонового завдання або короткого ланцюжка, де кожен крок легко повторити, вистачить вбудованих `Bus::chain()` і `Bus::batch()`. Вони простіші, не вимагають окремих таблиць і правил детермінованості.

Durable Workflow має сенс, коли:

- кроків багато, і повторне виконання вже зробленого дороге або шкідливе (платежі, листи клієнтам);
- процес триває години чи дні і чекає на людину або зовнішню систему;
- потрібна гілкова логіка між кроками, а не лише послідовність;
- хочеться бачити історію кожного запуску - для цього є UI [Waterline](https://github.com/durable-workflow/waterline).

Перш ніж переносити наявні процеси, врахуйте: зміна коду workflow, поки старі запуски ще не завершились, вимагає [версіонування](https://durable-workflow.com/docs/features/versioning/), бо старі запуски відтворюються на новому коді. Почати варто з одного нового процесу, а не з міграції всіх ланцюжків одразу.
