Typed Collection Laravel Package

Technical Evaluation

Architecture fit. gamez/typed-collection is a thin abstract subclass of Illuminate\Support\Collection that validates every item against a declared type on write and construction. Architecturally it is a boundary-hardening tool, not a framework: it adds no service provider, no config, no facade, no persistence layer. It fits where collections already exist as domain carriers — aggregate child lists, value-object bags, API response payloads, config-derived sets — and where the team already treats Collection as a public API surface. It is a poor fit for anything that needs Eloquent semantics (Model::newCollection()), lazy/streaming datasets, or collections used purely as ad-hoc arrays in controllers.

Integration feasibility. Low. composer require gamez/typed-collection, extend the base class, declare the expected item type, done. The real integration work is not installation but governance: deciding which collections become typed, and enforcing that convention in review and static analysis. Because it subclasses a vendor class, the Illuminate version constraint is the binding compatibility factor and must be checked against the application's current Laravel/PHP floor before anything else.

Technical risk. Concentrated in three areas:

• Invariant leakage. Laravel's map, filter, merge, flatten and similar methods return new static, so a typed subclass can be produced by a callback whose output violates the declared type. Confirm whether this package re-validates on those paths or only on push/put/offsetSet; if it does not, typing is advisory at transform boundaries.
• Ecosystem validation. 46 stars and 0 dependents means no downstream production evidence. The package surface is small enough to audit (a session, not a week), which materially reduces this risk.
• Maintainer concentration. Single-author, pre-1.0-scale adoption. Blast radius if abandoned is small — the class can be inlined or forked in under a day — so treat this as a contingency-plan exercise, not a blocker.

Key questions.

1. Which mutation and transform paths are validated, and what exception type is thrown (InvalidArgumentException vs. TypeError)?
2. Does it support interfaces, abstract classes, nullable/union types, and null items?
3. Does it ship PHPStan/Psalm generic annotations (@extends Collection<int, Foo>)? Without these, IDE and CI feedback is weak and the safety gain is runtime-only.
4. What is the illuminate/collections and PHP version constraint matrix, and is it tested against the Laravel majors we run?
5. Is construction O(n) validation on every new? Relevant only for large hydration paths.
6. Is serialization/json_encode/queue round-trip lossless, and how is rehydration into the typed class expected to happen?

Integration Approach

Stack fit. Native fit for Laravel 9–12 / PHP 8.1+ codebases that already depend on illuminate/collections; it also works framework-agnostically in any Composer project pulling Illuminate components. It does not slot in as an Eloquent collection replacement — that route requires newCollection() overrides and is a different, larger change.

Migration path. Do not retrofit. Introduce it forward-only in new or actively-refactored domain code, one bounded context at a time, and convert existing Collection returns only where a type violation would be a real defect (money, IDs, DTOs). For legacy arrays flowing in, wrap at the adapter layer and let the constructor do the validation. If the package fails the invariant-leakage question above, the fallback is a ~50-line in-house TypedCollection — cheap enough that build-vs-buy should be decided on the static-analysis story, not on code volume.

Compatibility. Pin the illuminate/collections constraint explicitly rather than relying on transitive resolution, and verify it against the framework version you actually deploy. Watch for collisions with packages that return their own Collection subclasses — those objects will fail type checks unless they extend your typed base. Confirm Laravel's package-discovery is a non-issue (it is: no provider).

Sequencing.

1. Spike: install in a scratch branch, write two typed collections, and empirically test map/filter/merge/push/put behaviour. This is the go/no-go gate.
2. Add PHPStan (or Psalm) with the package's generics and set the baseline; without this step the ROI is thin.
3. Adopt in a single bounded context behind existing interfaces so rollback is a one-line revert.
4. Document the convention in an ADR and add a CI rule (or a composer why-not style check) so future contributors do not silently revert to bare Collection.
5. Expand only after one release cycle with no invariant escapes in production.

Operational Impact

Maintenance. Near-zero ongoing cost: no migrations, no background jobs, no config, no runtime services. The ongoing cost is convention maintenance — keeping new code aligned and keeping the package constraint current with Laravel upgrades. Each Laravel major is a small manual compatibility review because the maintainer must ship a release first; budget a ticket per framework upgrade. Vendor the package or keep a fork branch ready given the single-maintainer profile.

Support. Community-only, no SLA, no commercial backing. Acceptable for a non-critical library with a trivial fallback; not acceptable if your release process requires vendor support agreements. The mitigation is that the entire dependency is auditable and replaceable.

Scaling. Runtime overhead is one type check per item on write and on bulk construction — negligible against typical request volumes, but O(n) when hydrating large arrays, so avoid it in hot loops over tens of thousands of rows. Memory profile is identical to Collection. No new failure surface at the infrastructure layer.

Failure modes.

• Runtime type exception at an unexpected boundary — often surfacing deep in a transform rather than at the input edge. Mitigate by validating at ingress and mapping to a 4xx where the input is user-supplied.
• Silent untyping — code returns Collection and the guarantee quietly disappears at a method boundary. Mitigate with return type declarations (: MyTypedCollection) enforced by static analysis.
• Framework upgrade breakage — Illuminate constraint unsatisfiable on the new Laravel major, blocking the upgrade. Mitigate by pinning and by having the fork contingency documented.
• Serialization drift — queue payloads and caches deserialize to plain arrays/Collections, losing the type. Mitigate by rehydrating explicitly at consumers.
• False confidence — the team assumes compile-time safety that is actually runtime-only. Mitigate by pairing adoption with PHPStan generics.

Ramp-up. Under an hour for a Laravel-fluent engineer: one class, one property, one exception. The larger ramp is cultural — teaching reviewers to spot where a typed collection is bypassed. A short ADR plus two example classes in the codebase is sufficient onboarding material.

TPM read. With 46 stars, zero dependents, and an opportunity score near 32, this is a low-cost, low-certainty bet: cheap to trial, cheap to abandon, but not a validated ecosystem choice. Recommend a two-day spike gated on the transform-invariant question and PHPStan annotations; approve only for new domain code, and treat the in-house alternative as a live option rather than a fallback.