Flow Laravel Package

Technical Evaluation

Position: darkwood/flow is a single-vendor, pre-1.x-equivalent PHP runtime for flow-based programming — an in-process async/functional composition engine, not a durable workflow or job system. It is technically interesting and cheap to trial, but the evidence does not support production adoption in a Laravel estate today. Recommendation: time-boxed spike only, behind an anti-corruption layer, with a pre-agreed kill criterion. Treat anything beyond that as a fork-and-own decision, not a dependency decision.

Architecture fit

• The model is Flow-Based Programming: an Ip (readonly data envelope) is pushed through a chain of single-argument callables yielded from a factory (FlowFactory::create), with a graph of typed stage-to-stage transforms (D1 → D2 → D3 → D4). Execution is driven by pluggable runtimes: AmpDriver, ReactDriver, SwooleDriver/OpenSwoole, FiberDriver, ParallelDriver, SpatieDriver, and an experimental TrueAsyncDriver for ext-async.
• Control surfaces are the DriverInterface (async, defer, tick, sleep, await), an event system (Event::POOL, SYNC, PULL), IpStrategy for ordering, IpPool for pooling, and AsyncHandlerInterface for batching/deferral at the sync step. That is a genuine runtime abstraction, which is the package's main architectural asset.
• It is orthogonal to Laravel's execution model. Laravel is request-per-process, sync-first, and durable work belongs to queues (Redis/SQS + Horizon). Flow offers concurrency inside a worker; it offers no evidence of persistence, replay, retries, dead-lettering, scheduling, or cross-node coordination — and Symfony Messenger support was explicitly removed in v1.2.6 after being added in v1.2.1–v1.2.2. Where it could fit: long-running workers (Octane/Swoole, FrankenPHP worker mode), streaming/chunked HTTP (there is an httpchunkflow.php example), and fan-out/fan-in transforms that are awkward as discrete queued jobs.
• Hard architectural gate: PHP 8.5 is the documented minimum. Current Laravel lines target PHP 8.2–8.4. Adopting Flow therefore couples to a platform upgrade program you probably have not funded, and to a PHP minor that the wider ecosystem (including some of Flow's own drivers) is still catching up to.

Integration feasibility

• Installation is trivial (composer require darkwood/flow, MIT). Everything after that is not.
• No Laravel integration exists or is claimed: the only first-party framework bridge is Symfony (AsJob attribute, Symfony-friendly packaging, Symfony-versioned releases). A Laravel service provider, config surface, container bindings for stages, queue-worker integration, and Octane lifecycle hooks are our build, not theirs.
• Dependency surface is heavy and mutually conflicting by design: amphp/amp v3, reactphp/async v4, OpenSwoole, plus Fibers. These collide with Octane's Swoole/RoadRunner pins and with existing promise-based code. Expect resolution work before the first line of Flow code is written.
• The monorepo consolidation (src/Darkwood/, darkwood/darkwood meta-package with replace aliases, splitsh subtree splits to satellite repos) means the repo under evaluation may be a split artifact rather than the source of truth, and Composer's replace aliases create real ambiguity about which code you actually installed. Verify provenance before pinning.
• Effort estimate for a credible evaluation: 3–5 days to get examples running on a PHP 8.5 container; 1–2 weeks for a wrapped spike with tests and metrics; 6–10+ weeks to make one pipeline production-grade (adapter, observability, error policy, load test, runbook).

Technical risk

• Vendor concentration / bus factor 1. 18 stars, 0 dependents, no downstream validation. Opportunity score 4.61 corroborates that the upside does not currently justify the carrying cost.
• Versioning is not a contract. Two parallel tag lines coexist (v1.x and 8.x where minor/patch track Symfony versions), v1.3.0 claims "unified Darkwood versioning" and is then followed by v8.0.12. Consumers cannot infer breaking changes from the version string, which forces exact pinning and manual upgrade review forever.
• Demonstrated breaking-change cadence: project rename (Railway FBP → Flow), namespace change (RFBP\ → Flow\), removal of IP-associated context, start/stop → await, Flow::do → FlowFactory::create, added-then-removed Symfony Messenger. This is healthy for a young library and hostile for a dependent platform.
• Documentation trust deficit. The README's primary example is not runnable: it references $ip->data->n3 inside a closure whose parameter is $data3, and closes printf with an unbalanced )). If the flagship snippet is not CI-executed, the examples/ directory and the GitHub Pages docs should be treated as illustrative, not authoritative.
• Observability regression. "Remove context associated with processing IP" (v1.1.1) removes the natural carrier for correlation IDs; re-establishing request/trace propagation across stages and drivers is our work.
• Debuggability. Fiber/coroutine stacks fragment, await() failures surface as driver-specific exceptions, and PHP tooling (Xdebug, Blackfire, APM agents) is immature for this execution model. On-call engineers will debug by inference.
• Key questions for the vendor before any commitment:
  1. What is the supported-version and backwards-compatibility policy, and is Flow\FlowInterface / DriverInterface frozen for a stated window?
  2. Which tag line is canonical for a non-Symfony consumer, and what is the supported PHP floor roadmap (8.5 fixed, or will 8.4 be supported)?
  3. Is there a Laravel/Octane integration on the roadmap, and who maintains it?
  4. What is the durability story — is persistence/replay deliberately out of scope, or delegated to an external transport?
  5. How are backpressure and memory bounded for IpPool and multi-IP pulls (PullEvent pulling multiple Ips)?
  6. What is the error taxonomy across drivers, and are Event::SYNC handler exceptions fatal to the flow or recoverable?
  7. Is there a security disclosure process, and who is the named maintainer with commit rights?
  8. Will you offer a support/commercial agreement, or is this best-effort community support?
  9. Are the README and examples/ executed in CI on every release?
  10. Is darkwood/flow a split from the monorepo — what guarantees that the split is not stale relative to src/Darkwood/?

Integration Approach

Stack fit

• Best fit is a contained async island, not a platform standard: a long-running worker (Octane/Swoole or FrankenPHP) performing CPU-light, IO-heavy graph transforms — chunked streaming, multi-source enrichment, fan-out/fan-in aggregation.
• Poor fit for anything requiring durability, retries, exactly-once semantics, scheduled execution, or multi-node coordination. Those stay on Laravel queues; do not let Flow become the system of record for work-in-flight.
• Assume no Laravel idioms: no auto-discovery, no config publishing, no facade, no artisan commands. Budget for that adapter explicitly.

Migration path

• There is nothing to migrate from; frame this as a pilot admission, not a migration. Phase 0: disposable spike branch/container on PHP 8.5, reproduce examples/flow.php and examples/server.php + client.php, publish a findings note. Phase 1: wrap behind an internal PipelineRunner interface with two implementations — Flow-backed and current queue-backed — so the pilot is reversible by config, not by revert. Phase 2: one non-critical, non-customer-facing pipeline behind a feature flag with a documented kill switch. Phase 3: expand only on a passed gate review.
• Never let Flow types (Ip, FlowInterface, driver classes) leak into domain code; keep the boundary at the adapter.

Compatibility

• Pin exact versions (no ^), commit composer.lock changes in isolated PRs, and add a CI job that installs the pinned set against your real PHP matrix. Given the tag-line churn, a minor/patch bump must be treated as potentially breaking until proven otherwise.
• Resolve the Swoole/OpenSwoole vs Octane pin conflict first — it is the most likely hard blocker. Confirm whether ext-async/TrueAsyncDriver is required (experimental) or optional; prefer a stable driver (FiberDriver or AmpDriver) for the spike to reduce variables.
• Sequence the PHP 8.5 platform upgrade as a prerequisite program with its own business case; do not smuggle it in as a dependency of a pipeline pilot. Verify the darkwood/flow install resolves to the intended source (satellite vs monorepo) and that replace aliases are not silently substituting packages.

Sequencing (stage gates)

1. G0 — Admissibility: license/security review, install-and-run examples in CI, provenance check, dependency-conflict report against Octane. Fail here and the answer is "no" for a year.
2. G1 — Spike: two representative pipelines benchmarked against the current queue implementation on latency, throughput, memory, and failure recovery.
3. G2 — Hardening contract: adapter interface, correlation-ID propagation, structured logging, error/retry policy, contract tests, load test, rollback rehearsal.
4. G3 — Pilot: single pipeline, feature-flagged, one named owner, documented SLO and abort criteria.
5. G4 — Decision review: adopt / contain / fork / drop, with an explicit statement of who owns patching if "adopt."

Operational Impact

Maintenance

• Realistically this becomes fork-and-own at any meaningful scale. Plan for a vendored or mirrored copy, a named maintainer, a quarterly upstream-diff ritual, and a documented patch policy.
• Upstream release cadence is coupled to Symfony and PHP releases, so upgrading Flow will periodically force platform upgrades on your schedule. That is an unbudgeted, recurring tax.
• Custom drivers and async handlers will break on minor bumps given the DriverInterface/AsyncHandlerInterface churn history; treat any extension of the driver layer as high-maintenance code.

Support

• Community support is effectively nil: 18 stars, 0 dependents, no visible SLA, triage process, security advisory channel, or LTS branch. Escalation is a GitHub issue to a single vendor.
• Either negotiate a commercial support agreement with a defined response target, or accept self-support and staff accordingly. If neither is acceptable, that is a "no" regardless of technical merit.

Scaling

• Scales by worker count and cores, not by adding nodes: concurrency is in-process. Swoole/OpenSwoole will outperform Fiber/React for coroutine-heavy IO, which means performance characteristics are a function of driver choice — a decision you cannot easily reverse later.
• No persistence or replay: a deploy, OOM, or uncaught exception loses in-flight Ips. There is no evidence of dead-lettering or poison-message handling; you must build it at the boundary.
• Backpressure and pool sizing for IpPool/IpStrategy are undocumented in the supplied materials; unbounded queues are the default failure shape. Load-testing memory under sustained multi-IP flow is mandatory before any pilot.
• Cross-node coordination is absent (CollectionTransport is in-process/collection-shaped; Messenger was removed). Horizontally scaling a stateful flow across pods is not a supported pattern.

Failure modes to design against

• Silent hang: $flow->await() never returns because a stage never resolves; without a timeout/watchdog this looks like a healthy idle worker.
• Blocking the sync step: a slow or throwing AsyncHandler at Event::SYNC stalls or kills the flow with driver-specific exception types.
• Memory growth: unbounded Ip pooling / multi-IP pulls under load.
• Runtime type breakage: stages are typed closures; a mid-flight class or signature change fails at runtime, not at build time — static analysis gives limited cover across the dynamic chain.
• Lost observability: correlation context was removed from Ip; without an adapter-level carrier, incident triage across stages is guesswork.
• Abandonment / drift: upstream goes quiet or the satellite repo lags the monorepo; your fork silently becomes the product.
• Platform coupling failure: a PHP 8.5 requirement lands ahead of your fleet's readiness and the pilot cannot be promoted.

Ramp-up

• The concept ladder is steep and stacked: flow-based programming plus futures/promises plus Fiber-based concurrency plus functional composition (the docs ship Y-combinator and Lambda/recursion examples). Senior PHP engineers without async-runtime experience will not be productive quickly.
• Estimate: 3–5 days for two senior engineers to run the examples and form an opinion; 3–4 weeks to ship a hardened pilot; 8+ weeks to on-call competence, including a runbook for the failure modes above.
• Hiring provides no shortcut — the talent pool with "Flow" experience is zero. You are training, and you need at least two trained people to avoid a new bus factor of one.
• Mitigation: designate a single accountable owner early, invest in a written internal guide with verified runnable snippets (do not trust the README's), and require the pilot to include a failure-injection exercise before promotion.