Collections Laravel Package

Product Decisions This Supports

• Build vs. buy for a commodity concern. Typed collections are a ~100-line problem most teams eventually solve in-house. v0.2 is the moment to decide: adopt, or spend a day writing an internal TypedCollection and stop carrying the dependency. This release makes "adopt" defensible for the first time, because the type parameter plus quality tooling closes the two gaps that usually push teams to build.
• Feature work that needs typed lists at boundaries. Domain entity sets, DTO pipelines, paginated results passed between service layers, and any place where array<int, Order> in a docblock currently does the work of a real type. The new collection type parameter turns those annotations into something static analysis can actually enforce and IDEs can autocomplete.
• Roadmap sequencing for static-analysis investment. Generic type parameters only pay off if the team runs PHPStan/Psalm at a meaningful level. If a "raise static analysis strictness" initiative is on the roadmap, this package becomes a cheap enabler; if it isn't, the headline v0.2 feature delivers nothing and adoption should be deferred.
• Dependency portfolio hygiene. A single-maintainer 0.x package with a deliberate 0.1.6 → 0.2 jump is a "tolerated dependency," not a platform commitment. The decision this supports is containment: wrap it behind an internal interface, so exit cost stays low regardless of what the maintainer does next.
• Use cases that clearly are not supported. Anything requiring Eloquent semantics, lazy/chunked iteration over large datasets, or collection macros should stay on Laravel's native Collection/LazyCollection. This package does not replace them and adopting it as a general-purpose collection layer would fragment the codebase.

When to Consider This Package

Consider it when:

• You are on PHP 8+ and already run static analysis in CI (PHPStan/Psalm) at a level where generic annotations are consumed rather than ignored.
• The pain you are solving is type drift in array-shaped data crossing service boundaries — not missing collection features.
• Your team is comfortable with @template-style generics and understands they are enforced by tooling, not the runtime.
• You can accept 0.x semantics: in 0.x, a minor bump is the conventional signal for breaking change, so upgrade checks must be manual.
• Footprint tolerance is high: single maintainer, small surface, no vendor SLA. Acceptable for a leaf-level utility; not for a load-bearing abstraction.

Look elsewhere (or build in-house) when:

• You need Laravel-native behaviour — Eloquent collections, lazy cursors, Collection macros, or framework-integrated helpers. Use the framework's own classes.
• You need predictable upgrade paths, security response commitments, or long-term support. A one-maintainer 0.x project cannot offer these, and a v0.3 could rename or reshape the type parameter.
• Nobody on the team will maintain the static-analysis baseline that makes the type parameter valuable — the upgrade cost then buys zero product benefit.
• You extend the collection class or construct it with loose/untyped arguments across many call sites. The 0.2 change touches the class's type signature, so subclasses and call sites are the most likely upgrade casualties; audit them before committing.
• The requirement is really "a small, well-tested value list" and a 30-line internal class plus code review covers it. Owning trivial code is often cheaper than tracking someone else's version churn.

Migration note for the upgrade decision: treat 0.1.6 → 0.2 as a potentially breaking minor. Do not float the constraint; pin ^0.2, run the suite and the static analyser, and check subclasses and any code passing untyped arrays. The "quality tools" addition is a genuine maturity signal — CI and analysis on the upstream repo reduce regression risk — but it changes nothing at runtime for consumers.

How to Pitch It (Stakeholders)

For executives (one paragraph): A small open-source PHP utility we are evaluating received a useful update: it now supports typed collections, which lets our tooling catch a class of data-shape bugs at build time instead of in production, and the maintainer added automated quality checks, which lowers the odds of a bad release. It is a micro-dependency, not a platform decision — low cost, low blast radius, and we can contain it behind our own interface so switching away later is a small job. Recommendation: approve a short, time-boxed evaluation rather than an org-wide standard.

For engineering leads: The v0.2 headline is a type parameter on the collection class, so the value is entirely realised through static analysis — it pays off only where PHPStan/Psalm are already enforced. The 0.2 bump is a pre-1.0 minor and should be treated as a possible breaking change for subclasses and loosely-typed call sites. Ask for a one-day spike: pin ^0.2, wire it into one service boundary, confirm the analyser reports cleaner types, and wrap it behind an internal collection interface. If the spike doesn't show measurably fewer type errors, we build the trivial internal version and move on.

For the sponsor signing off: Success criteria are concrete — improved analyser signal at one integration point, no subclass breakage, and an exit cost under a day. Anything short of that and the answer is "not now," which is a perfectly good outcome for a package this small.