Pipeline Laravel Package

Product Decisions This Supports

Build vs. buy. This is effectively a buy-nothing decision: illuminate/pipeline ships inside the Laravel framework you already depend on. There is no procurement, licensing, or vendor negotiation step (MIT), and no incremental infrastructure cost. The real decision is not "should we pay for this" but "should we standardize on it as our workflow abstraction," which is a standards and onboarding decision rather than a purchasing one.

Feature-level decisions it directly enables:

• Sequential business workflows as a product primitive. Onboarding steps, order fulfillment, KYC/document review, pricing and discount resolution, notification fan-out. Each step becomes a named, individually testable unit, which means a PM can reorder, insert, or A/B a step without re-architecting the feature.
• Gating and progressive rollout. Because steps can be conditionally included, feature flags become a pipeline composition concern rather than a code-branching concern. This lowers the cost of running two variants of a workflow simultaneously.
• Cross-cutting policy consistency. Auth, rate limiting, audit logging, and tenant scoping can be enforced as mandatory pipes instead of being re-implemented (and occasionally forgotten) in each endpoint or job. That is a compliance and reliability decision as much as an engineering one.
• Reusability across surfaces. The same pipeline can back an HTTP request, a queued job, and a console command. Product implication: behavior stays consistent whether a user triggers an action interactively or a batch process does it overnight — fewer "it works in the UI but not in the export" defects.

Roadmap sequencing. Adopting this pattern early in a Laravel codebase is cheap and compounds; retrofitting it into a mature monolith is a refactor with real regression risk. If the roadmap includes multi-step workflows (approvals, billing lifecycle, ingestion/ETL-adjacent flows), standardizing before those features are built is the lower-cost path.

Use-case fit matrix:

Portfolio-level caution. The package list shows zero dependents, which is a measurement artifact — it is consumed through laravel/framework rather than directly. Do not read that as low adoption. Conversely, do not read ~35k stars as product support: there is no vendor SLA, no roadmap commitment to your use case, and no dedicated documentation beyond the framework's. The maintenance risk is Laravel's release cadence, which is well-understood and predictable, not a solo-maintainer risk.

Metrics to instrument once adopted: per-step failure rate and latency, short-circuit frequency (which pipes are silently dropping payloads), and time-to-add-a-step. The last one is the real payoff metric — if adding a workflow step does not become materially cheaper, the abstraction is not earning its keep.

When to Consider This Package

Adopt when:

• The product is built on Laravel 8+ and the package is already present — the marginal integration cost is near zero.
• The feature roadmap contains genuinely sequential, order-dependent logic with three or more meaningful steps.
• The team wants steps to be individually testable, observable, and independently ownable by different engineers.
• Consistent policy enforcement across HTTP, queue, and console entry points matters (regulated, audited, or multi-tenant products).
• You expect the workflow to change over time — new steps, reordered steps, temporary experimental steps.

Look elsewhere when:

• Non-Laravel or non-PHP stack. The package assumes Laravel's container and contracts. Pulling it in means pulling in adjacent Illuminate components and fighting your existing framework. Symfony's HttpKernel/messenger, or a dedicated workflow engine, is the better fit. The technical assessment is blunt about this: integration feasibility is low outside Laravel, and the effort is "often not worthwhile."
• The logic is one or two steps. Procedural code is clearer, faster to read, and has no failure mode where a forgotten return silently passes null downstream.
• You need durable orchestration. Retries with backoff, compensation/saga semantics, long-running timers, human-in-the-loop waits, visual run history. This is an in-process pipeline, not a workflow engine; forcing those requirements onto it will end badly.
• The team has little Laravel experience. The pattern's sharp edges (silent null propagation, in-place mutation of shared payloads, exceptions halting the chain) are learned-the-hard-way edges. Budget for review conventions, not just adoption.
• You need contractual support or a vendor relationship. Community-maintained OSS with no commercial backing.

Non-negotiable preconditions if you adopt: a team convention that every pipe returns the payload explicitly; a rule that production pipes are invokable classes rather than closures; and at least one logging/observability pipe placed deliberately in the chain.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version: "We're proposing to standardize on a capability we already own. Laravel, our application framework, ships a built-in pipeline component that lets us express multi-step business processes — onboarding, order handling, validation, approvals — as a sequence of small, named, independently testable steps instead of one large block of code. The cost is essentially zero: no new license, no new vendor, no new infrastructure. The return is that changing a workflow becomes a configuration and ordering exercise rather than a rewrite, which directly reduces time-to-market for the workflow-heavy features on our roadmap and lowers long-term maintenance cost. The risk is low and the exit is trivial — it is a small, permissively licensed, widely used framework component. The main thing we're buying is a team convention, not a product."

For engineering — the honest version:

• It is already in the dependency tree; composer require is a no-op in a Laravel app. No new surface area to secure or upgrade separately — it moves with the framework.
• The value is compositional complexity management: pipes are small, mockable, and mockable individually, which makes the test suite express intent rather than implementation. Avoid closures in production pipelines for exactly this reason.
• The traps are known and cheap to mitigate, but they are real and should be written into the team's conventions up front:
  • Silent failure: a pipe that omits return $payload passes null to the next stage. Lint or review for it.
  • Mutation: pipelines mutate shared objects in place. Clone the payload wherever idempotency or retries matter.
  • Exception semantics: an uncaught exception halts the chain; decide deliberately between try/catch at the boundary and a terminal error-handling pipe.
  • Ordering: cheap, high-signal filters (auth, input validity) go first; database and third-party calls go later. This is a performance decision that is invisible in code review unless it's an explicit standard.
• Where we should not use it: anything requiring durable retries, compensation, scheduled waits, or cross-service coordination. Keep those on the queue/workflow tooling. Using this package as a workflow engine is the most likely way we get burned.
• Deliberate investment we should make: a logging/tracing pipe (or an extended Pipeline overriding handlePipe for per-step timings) so we get per-step latency and failure metrics out of the gate. Instrumenting after the fact is expensive; instrumenting at adoption is nearly free.

Bottom line for the decision meeting: adopt as a team standard for sequential, in-process workflow logic in Laravel services; explicitly scope out durable orchestration; spend a day on conventions and observability rather than on integration.