Download the PHP package adamczykpiotr/laravel-dag-workflows without Composer

dag-workflows

A lightweight library to define and dispatch directed acyclic graph (DAG) based workflows composed of Tasks and TaskGroups. Each Task can contain one or more jobs and may declare dependencies on other tasks. This package helps model, persist and execute complex multi-step workflows in Laravel applications.

Key features:

• Expressive workflow definitions using Workflow, Task and TaskGroup building blocks
• Support for single and grouped tasks
• Task dependencies and ordering
• Easy dispatching and inspection via Eloquent models
• Per-step progress reporting with built-in debounce
• rollbackStep() hook to undo a failed attempt's leftovers before a retry
• Pausable tasks for manual intervention (anomaly detection, user approval, etc.)
• Events for workflow state changes (paused, resumed, cancelled)

Installation

Install the package via Composer and run migrations:

Migrations ship with the package and run in place. If you want to customise the schema, publish them first: php artisan vendor:publish --tag="dag-workflows-migrations".

Usage

Below is a concise example showing how to define and dispatch a workflow. This example mirrors the structure of the included tinker snippet but models an "Image Import Pipeline":

Reporting progress

Jobs using HasWorkflowTracking can call $this->progress(int $percentage) (0–100). Writes are debounced against the step row's updated_at (30s window); 100 and progress(..., force: true) always write.

Rolling back failed attempts

When a step is retried, the previous attempt may have left things behind — a downloaded file, rows from queries that already ran. Override rollbackStep() to undo them; it runs right before handle(), but only when a previous attempt of the step already ran. First attempts skip it, and the default is a no-op, so existing jobs are unaffected. A throwing rollbackStep() fails the step like a throwing handle().

This also covers steps re-run because an upstream step was retried: if the step already ran, it rolls back first; if it never ran, it starts clean.

Pausable Tasks

Workflows, tasks, and steps can be paused for manual intervention. This is useful when:

• An anomaly is detected that requires human review
• User approval is needed before continuing
• External validation is required

The package dispatches events (WorkflowPaused, WorkflowResumed, WorkflowCancelled) that you can listen to for notifications and integrations.

For comprehensive documentation including job examples, event handling, and best practices, see docs/PAUSABLE_TASKS.md.

Early Task Completion

A job can complete its whole task early when the remaining steps are known to be unnecessary — for example when a freshly downloaded source file is byte-identical to the one already processed:

The current step is marked COMPLETED, all remaining steps of the task are marked SKIPPED (a terminal, non-failing status), and the task completes as if every step had run — dependant tasks are dispatched and the workflow status is finalized as usual.

Workflow endpoint formats

WorkflowController::show defaults to a lightweight summary — no dependency wiring, no estimator:

SKIPPED counts as done in the percentages (it is the terminal, non-failing status of steps bypassed by an early task completion), and stepProgressPercentage additionally credits running steps with their self-reported progress. Append ?format=failed for the full payload with tasks filtered to failed tasks only (each with all of its steps, no other tasks loaded), or ?format=full for the previous behaviour: the complete tasks/steps tree with dependencies and timing estimates. All three payloads are documented field-by-field in docs/WORKFLOW_ENDPOINT.md.

Dynamic dependencies (waiting for a ResolvableTask's spawned tasks)

A ResolvableTask completes once its resolver has spawned the child tasks — depending on it by name therefore does NOT wait for the children. A dependency ending with * is a prefix glob: it gates the task on every OTHER task whose name starts with the prefix, including tasks that only come into existence at runtime:

The declaring task never matches its own wildcard, so the aggregate may live in the namespace it waits for. At least one other task must match the glob at definition time — that anchor keeps the dependant parked until runtime-spawned matches (which are wired in while their resolver is still running) have been attached.

* is reserved for this syntax — task names containing it are rejected with a WorkflowTaskReservedCharacterException.

Limiting ResolvableTask items per environment

config/dag-workflows.php points at a middleware applied to the items before tasks are materialised. The default is PassthroughMiddleware although for testing purposes there's also handy implementation of TakeFirstMiddleware.

Custom middlewares have to implement WorkflowResolvableItemsMiddleware::handle(iterable $items): iterable interface.

Testing

Run the package and application tests:

Contributing

Contributions are welcome. Please read CONTRIBUTING.md in the repository for guidelines.

Security

If you discover a security vulnerability, please follow the repository's security policy to report it.

Credits

• Piotr Adamczyk (maintainer)
• All contributors

License

The MIT License (MIT). Please see License File for more information.