Pipeline Laravel Package

Product Decisions This Supports

• Build vs. buy for data-transformation plumbing. The package replaces hand-rolled nested foreach/generator code used for imports, exports, feed ingestion, and report generation. At Apache-2.0 with no transitive dependency risk, the "buy" cost is a composer require and a code-review.
• Memory-constrained feature work. Because evaluation is lazy and generator-backed, features that currently force ->get() on a large result set (full-table exports, CSV/NDJSON processing, audit-log scans, sitemap or feed builds) can ship without raising PHP memory limits or adding chunking logic to every job. This is a direct enabler for roadmap items currently blocked on "too much data in memory."
• Readability as a delivery metric. The fluent chain (take()->map()->filter()->fold()) collapses multi-screen transformation blocks into a reviewable sequence. Fewer intermediate arrays and loop variables means fewer off-by-one and key-collision defects — measurable as reduced defect rate on ingestion/reporting tickets.
• Specific capabilities that are awkward to build in-house: single-pass online statistics (mean/variance/stddev via Welford) for dashboards without a second aggregation query; weighted reservoir sampling for statistically defensible spot-checking and sampling in QA/analytics; chunkBy/chunk for batched writes and rate-limited API fan-out; cursor() for resumable, partial consumption; zip/unpack for transposing parallel sources.
• Use-case fit: background jobs and Artisan commands, ETL between systems, log and event stream reduction, paginated third-party API consumption, batch notifications, and any pipeline where "process item, discard item" is the correct memory model.
• Explicitly not a fit for: domain-model logic, request-scoped collection manipulation in controllers, or anywhere the team expects an immutable value object. The API is deliberately mutable and single-use; adopting it broadly would trade one class of bugs for another.

When to Consider This Package

Adopt when most of the following hold:

• Runtime is PHP 8.2+ and the codebase is framework-agnostic or the team is willing to use a non-Laravel primitive alongside Laravel's own tooling.
• The data is already an iterable, is large, unbounded, or streamed from a DB cursor, file handle, or HTTP paginator.
• The transformation is a linear sequence of stages (map → filter → cast → fold) rather than a graph with branching, caching, or backtracking.
• You want the pipeline confined to a boundary layer — importer, exporter, job, report builder — with a thin internal wrapper so it can be swapped later.
• Correctness under adversarial input matters more than feature breadth: 100% line coverage, mutation testing, and multiple static analysers are genuine procurement signals for a low-star package.
• You value that the library defines and throws no exceptions — failure modes are "empty result," which is acceptable for batch/scheduled work but must be paired with your own assertion/observability layer.

Look elsewhere when:

• Laravel is the whole context. Illuminate\Support\LazyCollection already covers the majority of this surface with first-party support, framework conventions, and a maintenance guarantee. Introducing a second lazy-collection vocabulary into a Laravel codebase is a real cognitive tax; the justification has to be the specific gaps — weighted reservoir sampling, online variance, cursor(), unpack/tuple transposition.
• You need immutability, safe re-iteration, or thread/process safety. Pipelines are mutable and not rewindable; re-consuming a pipeline is undefined behaviour and will throw PHP generator errors.
• You need vendor accountability: one maintainer, ~74 stars, and zero dependents means no ecosystem validation and no external pressure to fix your bug. Treat it as "vendored source you happen to install via Composer," not as infrastructure.
• The workload needs parallelism, async I/O, or backpressure — this is single-threaded pull-based iteration.
• The team is uncomfortable with generators and lazy semantics. The "almost nothing happens unless you consume the results" caveat is the single most likely source of production surprises and on-call pages.

How to Pitch It (Stakeholders)

For executives: A small, permissively licensed PHP utility that lets us process large data sets in constant memory instead of loading them whole. It is a tactical enabler for a handful of roadmap items currently blocked on memory limits, costs nothing to license, and is isolated behind our own wrapper so it is cheap to remove. It is not a platform bet — we are not adopting a vendor, we are adopting a well-tested helper.

For engineering leadership: It removes repeated bespoke generator code from ingestion and reporting paths, and it ships with the quality signals we normally ask for in-house — full line coverage, mutation testing, PHPStan/Psalm at strict levels, and documentation kept in sync with the public API. Two risks we manage explicitly: (1) it is effectively single-maintainer with no downstream dependents, so we pin the version and confine usage to a small set of boundary classes; (2) its mutable, non-rewindable semantics differ from LazyCollection, so we standardise on one idiom per codebase and document the "consume it or nothing happens" rule in the PR template.

For the engineering team: One rule — use it in jobs, commands, importers, and exporters, not in domain code or controllers. Wrap it. If a chain needs to be re-read, use cursor() or materialise with toList(); never iterate a pipeline twice. Prefer toList()/toAssoc() over iterator_to_array() to avoid silent key collisions.

Decision requested: Approve a time-boxed pilot on one ingestion path and one report builder, measured on peak memory and code volume, with the wrapper in place from day one. If the pilot does not show a clear win over LazyCollection, we drop it and keep the wrapper.