Collections Php Laravel Package

Product Decisions This Supports

• Feature-level architectural decision: typed domain collections vs. raw arrays. This package lets you wrap arrays in collection objects that keep array-style access while adding behavior. As a PM this is the lever for a very specific class of decision: whether a domain aggregate (Order, LineItem, ImportBatch) should expose a collection type with its own vocabulary (e.g. total(), unshipped(), groupedBySku()) instead of an array plus a separate service class. That's a design decision with product consequences — it moves business rules next to the data they operate on, which reduces the surface area for "we asked for items and got lineItems" defects.
• Defect-class elimination, not a feature. The clearest product value is measurable against your bug tracker: if you see a recurring cluster of Undefined array key, silent shape drift between producer/consumer, or "this collection was mutated somewhere downstream" bugs, this package is a candidate remediation. If that cluster doesn't exist, there is no product case.
• Immutability as a quality lever in async/concurrent paths. Mutable/immutable collection variants matter most in queue workers, jobs, and event listeners where a shared array gets modified mid-flight. This is a reliability decision, not a developer-ergonomics decision.
• Build vs. buy: effectively "buy at zero cost, with maintenance liability." MIT-licensed, no infrastructure, no runtime services. But it is a single-maintainer package with ~10 stars, zero dependents, and a last release of December 2023. Treat adoption as incurring a maintenance obligation, not as a free win.
• Explicitly not a roadmap item. This is plumbing/hygiene. It should never consume roadmap capacity, and adoption should never be gated on it.
• Pipeline/transform use cases. Data import, export, report generation, and ETL-shaped transformations are where chained map/filter/reduce reads best and where the sugar pays for itself.

When to Consider This Package

Adopt (narrow, bounded pilot) when:

• You require runtime-enforced immutability in a specific module. Laravel's Illuminate\Support\Collection is not immutable — push, pop, shift, transform, splice mutate in place. If a module's correctness depends on collections being value objects, the framework collection will not give you that.
• You require runtime type enforcement on elements (throw on wrong type), not just PHPStan/Psalm docblock generics. Static analysis catches this at CI time; this package catches it at runtime in production paths.
• The code is domain code that deliberately avoids Eloquent — import/export pipelines, report builders, integration adapters — where Illuminate collections would drag in framework assumptions you don't want.
• The team is willing to read the source as the documentation. There is no tutorial corpus, no Stack Overflow history, no third-party content for a package this size.

Look elsewhere (default recommendation) when:

• Illuminate\Support\Collection + LazyCollection + Arr already cover it. For most Laravel work, the correct buy decision is "use what's in the framework, add phpstan/phpstan with generics docblocks." That gets you most of the type safety with zero new dependency, zero new maintenance, and a large hiring/onboarding pool. This package's advantage over Illuminate is narrow: enforced immutability and runtime element typing.
• There is no Laravel integration surface at all. No service provider, no facade, no config file, no publishable assets. That means zero boot cost — but also zero idiom alignment. It is a plain Composer library you happen to install in a Laravel app, not a Laravel package. Don't let it be pitched internally as "a Laravel package."
• Long-term support or security posture is a requirement. Single maintainer, one-person bus factor, no visible release cadence since Dec 2023. PHP 8.3/8.4 deprecation drift is an ongoing tax you will pay yourself.
• Team seniority is mixed. Every non-framework abstraction is a concept the next hire must learn from source. Budget that onboarding cost honestly.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed PHP utility that wraps arrays in typed, optionally immutable collection objects. It is not a platform change, has no runtime footprint, and costs nothing to license. The honest framing is a bounded experiment: pilot it in one module where we can measure a specific defect class (array-shape and unintended-mutation bugs), and keep the exit cheap. The risk is maintenance, not technology — it is a single-maintainer open-source project with a small user base and no release since late 2023, so we should not make it a load-bearing dependency across the codebase. Recommendation: do not adopt broadly by default; pilot only where the defect data justifies it.

To engineering: It's syntax sugar over arrays — you keep array-style access and gain typed elements plus mutable/immutable variants. There is deliberately no service provider or facade, so it's an ordinary Composer dependency, not another framework layer. The counter-argument to take seriously: Illuminate\Support\Collection plus PHPStan generics already covers ~80% of the value, and we'd be trading a large, well-documented, framework-maintained API for a small one whose documentation is its source code. The only reasons to prefer it are (a) enforced immutability and (b) runtime element type checks — so the pilot should target exactly a module that needs both. Success criteria: measurable reduction in array-shape defects in that module and no new onboarding friction beyond one afternoon of reading source; failure criteria: anyone reaching for Illuminate\Support\Collection alongside it "because it's easier," which means we've added a concept without removing one.