Typed Collections Laravel Package

Product Decisions This Supports

• Enforcing domain invariants at collection boundaries. The package's only real job — guaranteeing every element of a collection is an instance of a declared type — maps to a recurring product risk: a Collection of "users" that silently contains an array, an Eloquent model of the wrong class, or a raw scalar after a refactor. Decisions it informs: whether our service layer returns typed collections or bare Illuminate\Support\Collection, and whether that contract is enforced at runtime or only asserted in tests.
• Build vs. buy for a ~1-afternoon capability. The mechanism is a thin subclass of Laravel's Collection that overrides item-insertion paths (offsetSet, push, constructor) and throws on mismatch. That is small enough that "buy" (add a dependency) is almost never the right answer versus "build" (a 40-line abstract base class we own) — and this package is archived, which closes the buy option anyway.
• Runtime enforcement vs. static analysis as the house standard. This package represents the runtime-check camp. The competing options are PHPStan/Psalm @template/@extends annotations on Illuminate\Support\Collection, Collection::ensure() for one-off assertions, and PHP 8 typed properties/readonly for the elements themselves. Choosing one of these is a standards decision with real cost implications (CI config, developer education, review checklists), and this package is a useful artifact for framing that trade-off.
• Feature-level use cases worth scoping: API resource collections, event/DTO payload lists, import pipelines, report row aggregation, and anywhere a collection crosses a module or service boundary and is consumed by code that assumes a shape.
• Roadmap signal — negative. An 11-star, archived-since-2017 package is a data point for a "no unmaintained dependencies" policy and for prioritizing PHP 8 modernization (enums, readonly, union types) over adopting legacy abstractions.

When to Consider This Package

Consider it as reference material, not as a dependency, when:

• You are drafting an internal typed-collection base class or a code-review rule ("collections returned from *Service must be typed") and want a minimal prior-art example to sanity-check scope and API shape.
• You need to justify in-house work: reading the implementation is the fastest way to show stakeholders the capability is small, well-understood, and not worth a third-party risk surface.
• You are teaching the difference between runtime guarantees and static-analysis guarantees to a team standardizing on PHPStan generics.

Look elsewhere — i.e., do not adopt — when:

• Any production use. Last release 2017-07-27 and archived. No PHP 7.4+ typed properties, no PHP 8 union/intersection types, no enums, no readonly; unverified against Laravel 8/9/10/11 and against illuminate/collections split-package versions. No security response path, no issue triage, and 11 stars means effectively no user base to surface breakage.
• You need generics or nested typing. A single protected $type string cannot express Collection<int, Collection<int, Money>>; static analysers can.
• Better-fit alternatives exist: Collection::ensure() plus Illuminate\Support\Collection for assertions; PHPStan/Psalm @template docblocks for compile-time enforcement; hand-rolled collection subclasses overriding offsetSet/push for domain-specific collections; Spatie laravel-data or similar for typed DTO collections with validation and transformation built in.
• Your upgrade cadence is faster than the package's. Any Laravel major upgrade turns an archived dependency into a fork you now maintain — cost that exceeds writing the class yourself.

How to Pitch It (Stakeholders)

For executives (30 seconds). We evaluated vistik/typed-collections, a small library that makes Laravel collections enforce a single element type. Recommendation: do not adopt. It is archived, last released in July 2017, has negligible community footprint, has never been validated against current PHP or Laravel versions, and carries no security-maintenance commitment. The capability it provides is approximately one afternoon of engineering to reproduce in-house with modern PHP 8 types and static analysis — which we would own, test, and upgrade on our own schedule. Adopting it would add a supply-chain and upgrade-blocker risk for negligible return; the sensible action is a short internal spike, not a dependency.

For engineering leads. Read the source as prior art, then write our own. A TypedCollection extends Illuminate\Support\Collection that overrides offsetSet, push, and the constructor to throw InvalidArgumentException on a wrong element type is roughly 40 lines and fully testable. Pair it with PHPStan @template/@extends annotations so violations fail in CI, not at runtime in production — that gives us both a static guarantee and a runtime backstop, which this package alone cannot. Prefer Laravel's built-in ensure() for one-off assertions rather than introducing a base class everywhere. Also note the package predates PHP 7.4 typed properties and PHP 8 enums, so its design will feel dated in review and shouldn't be used as an API template without modernization.

Known risks and decision triggers. Risks: archived maintenance status, no PHP 8 / current Laravel compatibility, single-type-only expressiveness, and a fork burden at the next Laravel major. Trigger to revisit: if the team's in-house implementation proves insufficient for nested or generic element types, evaluate laravel-data or a static-analysis-first approach rather than returning to this package. Verdict: reference-only; keep out of composer.json.