Piper Laravel Package

Product Decisions This Supports

• Build vs. buy for internal DX utilities. Every Laravel shop eventually accumulates a grab-bag of curried helper functions, Str::of() chains, and one-off collect() pipelines. Piper is MIT, Spatie-maintained, and ports Laravel's own collection/string semantics, so the realistic alternative is not "build this" but "keep hand-rolling it." Frame adoption as standardize on an existing idiom rather than add a dependency.
• Codebase readability as a roadmap item. The package's only real deliverable is legibility of transformation code: linear, top-to-bottom pipelines instead of nested calls or temp variables. That makes it a lever for onboarding time, review velocity, and defect rate in business-logic-heavy files (report builders, exports, notification bodies) — measurable via PR review cycle time and reviewer comments on those files, not via any runtime metric.
• Timing the PHP 8.5 upgrade. This is the single strategic dependency. Piper is inert below PHP 8.5 (|> doesn't exist; Composer resolution fails). Adopting it converts the PHP 8.5 upgrade from "hygiene" into "unlocks a tooling improvement," which is a useful forcing function — or, read the other way, adoption is gated entirely on an upgrade the org must already have funded for its own reasons. Don't let Piper be the justification for a risky runtime jump.
• Scoping a low-blast-radius pilot. The package is ideal for a bounded experiment: pick one existing 3+ step array/string transformation (report row builder, CSV import normalization in a queued job, seeder/fixture generation, prepareForValidation, artisan utility) and ship it as one PR. Decision criteria afterwards: does the diff read better in review? Low cost of being wrong — one file reverts.
• Setting a house idiom before entropy wins. The real product decision is a style-guide entry: pipes for 3+ transformation steps over primitives; collect() for Eloquent-centric or lazy paths; plain loops for hot paths. Left unwritten, the predictable outcome is three idioms in one file — which is worse than either idiom alone.
• Vendor and hiring signal (secondary). Spatie is a known-quantity vendor in the Laravel ecosystem and the API mirrors Laravel's own method names, so "if you know Collection, you know 90% of this" is a true statement you can put in an onboarding doc. Modest but real recruiting/retention value for Laravel-specialist teams.
• Explicitly not supported: performance decisions. Every stage is eager and builds full intermediate arrays. Piper must not be selected as a fix for slow transforms; it's a readability purchase, and it should never appear in a hot loop or a path currently protected by LazyCollection.

When to Consider This Package

Adopt (or pilot) when all of these hold:

• PHP 8.5 is already in production or fully funded and scheduled, including your CI matrix (PHPStan/Psalm must also run on 8.5 to parse |>), config.platform.php, and your deploy base image.
• The codebase has a meaningful volume of 3+ step array/string transforms currently expressed as collect() chains, nested helpers, or sequential temp variables — i.e., there's a real surface area to improve.
• The team is Laravel-fluent, so the API is essentially free to learn, and static analysis is mature enough to validate use function group imports before they enter a style guide (function imports weaken find-usages, rename refactors, and autocomplete relative to method calls).
• You want a convention more than a capability, and you're willing to own the house rule that scopes where pipes are acceptable.
• MIT license and zero infrastructure (no service provider, no config, no publish step) fit your dependency policy; one composer require and it's done.

Look elsewhere when any of these hold:

• You're below PHP 8.5. Not a soft preference — hard blocker. Don't adopt-and-hold; the package does nothing until the runtime moves.
• No credible PHP 8.5 timeline. Then the correct PM answer is "revisit at upgrade planning," not "add to backlog."
• You need ecosystem provenness. 57 stars, 0 dependents, first stable release recent, one minor version. Spatie's reputation offsets a lot, but this specific package has essentially no production track record elsewhere. If your dependency policy requires demonstrated adoption or an SLA, this fails today.
• Your code is already Collection/Stringable-shaped end to end. The value proposition is primitive-in, primitive-out pipelines with explicit conversion seams at the boundaries. If everything is already object-chained and consistent, you'd be buying a second idiom, not removing one.
• Performance or large-dataset paths are in scope. Eagerness makes it wrong for high-throughput work; generators or LazyCollection are the answer there regardless.
• You want debuggability inside an expression. You can't dd() between stages (|> dump() evaluates eagerly and pipes null; |> dump(...) is required, and even then return-value semantics bite). Teams that debug primarily by inserting dumps mid-expression will feel this as friction, not improvement.

How to Pitch It (Stakeholders)

One-liner for executives: A free, MIT-licensed readability upgrade for our PHP data-transformation code — adopted with one Composer command, no infrastructure, no vendor contract — but it only switches on once we're on PHP 8.5. Cost: roughly one engineer-week to pilot and document. Risk: low and reversible.

For engineering leadership: The package adds zero new capability — everything it does today is already possible with collect() and Str::of(). What it buys is a standardized, linear, top-to-bottom expression of multi-step array/string transforms, which shows up as faster review, cleaner diffs, and easier onboarding in exactly the files that are hardest to read (report builders, exports, notification bodies, import normalization). Because it's a pure-primitives library, its output is trivially unit-testable with plain assertions — no container, no database.

The honest caveats to state up front, not after the fact:

• Hard prerequisite: PHP 8.5. Including static analysis and the deploy image. This is the whole schedule.
• Small track record. 57 stars, zero dependents, recent 1.0 line. Vendor pedigree is strong; package-level evidence is thin. Mitigation: pilot scope limited to one PR, and no style-guide mandate until it survives our static analysis.
• It's a convention, not a feature. Success is only measurable if we write the rule down (pipes for 3+ step primitive transforms; collect() for Eloquent/lazy; loops for hot paths) and review for it. Without that, we'll end up with a third idiom alongside the two we already have — a net readability loss.
• Eager by design. Must be carved out of performance-sensitive paths in the same breath as adoption.

Recommendation: Approve a bounded pilot — one existing 3+ step transformation, one PR, one measured before/after read in review — contingent on the PHP 8.5 upgrade already being funded. Defer the style-guide mandate and any broader rollout until the pilot clears and static analysis is verified on 8.5. Do not treat this as a reason to accelerate the runtime upgrade.