Weave Code
Typed Collection Laravel Package
gamez/typed-collection
gamez/typed-collection adds type-safe, strongly typed collections to Laravel and PHP. Define the item type once, keep the familiar Collection API, and get better IDE autocompletion, static analysis, and early errors when invalid values are added.
Type-safe collections based on Laravel Collections
Frequently asked questions about Typed Collection
- What is gamez/typed-collection and when should I use it instead of a plain Laravel Collection?
- gamez/typed-collection is a thin abstract subclass of Illuminate\Support\Collection that validates every item against a declared type when the collection is constructed or written to. Use it where a collection is a domain carrier, such as aggregate child lists, value-object bags, money or ID sets, or API response payloads, and where a wrong type would be a real defect. It is not a fit for ad-hoc arrays in controllers, lazy or streaming datasets, or anything that needs Eloquent collection semantics. Think of it as boundary hardening rather than a framework feature.
- How do I install gamez/typed-collection in a Laravel application?
- Install it with Composer using composer require gamez/typed-collection. There is no service provider, config file, or facade to register, because the package only adds a base collection class. The integration work is extending that class, declaring the expected item type, and deciding which collections in your codebase should become typed. Pin the illuminate/collections constraint explicitly rather than relying on transitive resolution.
- Which Laravel and PHP versions does gamez/typed-collection support?
- The package depends only on illuminate/collections, so its Illuminate version constraint is the binding compatibility factor rather than the full framework version. Check that constraint against the Laravel and PHP floor you actually deploy before adopting it, since it is designed for modern PHP 8.1+ codebases on Laravel 9 through 12. Because it subclasses a vendor class, a Laravel major upgrade can affect it even if nothing else in your app changes.
- How do I create a typed collection class with this package?
- Extend the package's base class and declare the item type the collection accepts, then use it anywhere you would use a normal Collection. Construction validates the initial items, so you can wrap legacy arrays at an adapter layer and let the constructor reject bad values early. The public API stays the familiar Laravel Collection API, which keeps the learning curve low for a team that already knows collections.
- What exception is thrown when I add an invalid item to a typed collection?
- The package rejects items that do not match the declared type at construction and on write paths such as push, put, and offsetSet. The exact exception class, whether InvalidArgumentException or TypeError, is worth confirming in the source for the version you install, because your tests and error handling should assert on it. Decide upfront whether you want to catch these errors at a boundary or let them bubble as programmer errors.
- Does gamez/typed-collection validate items produced by map, filter, merge, or flatten?
- This is the key question to verify before relying on it. 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. If the package only validates on push, put, and offsetSet, then typing is advisory at transform boundaries and you should re-validate or cast when a transform changes the item type. Audit the transform paths your code actually uses rather than assuming full coverage.
- Can I use interfaces, abstract classes, nullable types, union types, or null items as the declared type?
- Support for interfaces, abstract classes, nullable and union types, and plain null items depends on how the package implements its type check, so confirm it against the version you install. Interface and abstract-class support matters most in domain code, where child collections often hold a contract rather than a concrete class. If null items are rejected when you need them, wrap the value or adjust the declared type rather than loosening the collection.
- Does gamez/typed-collection ship PHPStan or Psalm annotations for IDE autocompletion?
- The safety gain is much larger if the package provides generic annotations such as @extends Collection<int, Foo>, because those give IDEs and static analysis tools the item type inside map, filter, and foreach loops. If generics are not shipped, add them to your own subclasses so PHPStan or Psalm can follow the type through your code. Without them, the benefit is runtime-only, and the build-versus-buy decision should be made on the static-analysis story rather than on code volume.
- Can I use gamez/typed-collection with Eloquent models or as a replacement for Eloquent collections?
- It is not an Eloquent collection replacement. Routing models through it requires newCollection() overrides on your models and is a larger, different change with its own risks. A more practical pattern is to convert Eloquent results into a typed collection of DTOs or value objects at the boundary, keeping the typed collection for domain code and leaving Eloquent semantics to Eloquent.
- Is gamez/typed-collection production-ready, and what are the alternatives if it is abandoned?
- It is a small, auditable package with a single author and limited downstream adoption, so there is no broad production evidence to lean on. The blast radius is small: the class is thin enough to inline or fork in under a day, so treat abandonment as a contingency plan rather than a blocker. The real alternative is a roughly 50-line in-house TypedCollection, so decide between them on the static-analysis and validation coverage, not on code volume.
Weaver
How can I help you explore Laravel packages today?