Fancy Flow Php Laravel Package

Getting Started

Install the package with Composer, publish/run any migrations or config, then start with the graph-definition API and the for_each / subgraph documentation. The first practical use case is a queued workflow that fans out over a collection with for_each and reports per-item progress to the host application. As of v0.64.0, nested runs now forward node-status, node-message, and log events to the parent, so per-item progress and logs are actually observable from the host.

First things to inspect:

• How graphs, nodes, and edges are defined.
• How for_each item lanes are addressed, e.g. each/0/body, each/1/body.
• How subgraph composes an inline graph.
• RunEvent and RunEvent::forParent() for event forwarding.
• Checkpoint/resume behavior, since checkpoints are what durable execution reads.

Implementation Patterns

• Use graph-level fan-out instead of PHP loops when you need per-item visibility. Put the per-item body in a for_each lane so each item gets its own checkpoints, statuses, messages, and logs. Do not loop inside a single executor if you expect per-item progress events.

• Compose reusable workflows with subgraph. Nested node events now bubble to the host, so a parent workflow can listen to progress from an inline child graph without custom forwarding.

• Keep durability and observability separate. Checkpoints drive resume; events drive dashboards, logs, and user-facing progress. Test both independently.

• Listen for RunEvent in Laravel and filter by address. A listener should inspect the event type and address rather than assuming every node event belongs to a top-level node.

use Illuminate\Support\Facades\Event;
use Vendor\Package\Events\RunEvent;

Event::listen(RunEvent::class, function (RunEvent $event) {
    // Nested node events now arrive with addresses like each/0/body.
    // Run-scoped events from nested lanes are not forwarded.
    $address = $event->address;

    if (str_starts_with($address, 'each/')) {
        // Update per-item progress, logs, or UI state.
    }
});

• Render progress from addresses, not counts. Store the run ID plus the event address. For each/{index}/body, use the index to map back to the item being processed.

• Queue long-running graphs. Fan-out workflows can be slow and IO-heavy. Use Laravel queues/Horizon, set sensible retries and timeouts, and make nodes idempotent because resume may re-enter work.

• Reuse RunEvent::forParent() in custom executors. If you build your own nested executor, use the centralized re-addressing helper rather than copying the forwarding condition. The release notes explicitly call out that duplicated forwarding logic is how both executors became identically wrong.

• Test event streams, not just checkpoints. A durable test can pass while node events are silently dropped. Add listener-level or event-assertion tests for node-status, node-message, and log, especially for for_each lanes.

Gotchas and Tips

• Do not assume every node-status is top-level. After upgrading, nested node events from for_each and subgraph reach the host. Read the event address, such as each/0/body, instead of relying on event counts or ordering.

• Run-scoped events are deliberately not forwarded from nested runs. A lane’s run-start, run-end, and run-error are not the parent’s lifecycle. Do not wait for a run-start per item or treat a nested lane as a separate top-level run.

• Checkpoints are not a substitute for event tests. Checkpoints survived the bug because resume depends on them. If your UI, logs, or metrics depend on node events, assert those events directly.

• Upgrade impact is limited but real for event consumers. Most applications need no code changes. Hosts that counted events or assumed all node events were top-level should review listeners, dashboards, and broadcast payloads.

• Treat addresses as paths, not rigid three-part strings. each/0/body is an example, not a guarantee that every address has exactly three segments. Use package helpers where available and avoid brittle splitting if node names can contain slashes.

• Debug with run ID, event type, address, and node identity. Correlate event addresses with checkpoint records when investigating missing progress or duplicate work.

• Queue or defer heavy event listeners. Broadcasting per-item progress or writing per-event database rows can add significant overhead during fan-out. Use queued listeners and batch updates where possible.

• Use RunEvent::forParent() as the extension point. It is the single implementation used by both for_each and subgraph; custom executors should follow the same path to keep event forwarding consistent.