Doctrine Collections

Doctrine Collections is a PHP library that layers a Collection abstraction on top of native arrays, giving developers a consistent, object-oriented API (map, filter, forAll, matching, and more) instead of the inconsistent function-based array_* API PHP ships with. Its ArrayCollection implementation backs collection-valued properties across the Doctrine ecosystem, most notably Doctrine ORM’s to-many associations.

Beyond basic iteration, the library ships a Criteria/Expr system for building composable, storage-agnostic filter expressions and an AbstractLazyCollection base class so collections backed by a database query can defer loading until they’re actually accessed. Because it has no framework dependency, it is equally usable as a general-purpose collections library outside the Doctrine stack.

What You Get

• Collection and ReadableCollection interfaces with a consistent map/filter/forAll/matching API
• ArrayCollection, a ready-to-use in-memory implementation of Collection
• Criteria and ExpressionBuilder for building composable, storage-agnostic filter/sort expressions
• AbstractLazyCollection base class for deferring collection population until first access
• Selectable interface so any collection can be queried with a Criteria object

Common Use Cases

• Modeling to-many associations in Doctrine ORM entities (e.g. $order->getItems())
• Replacing ad-hoc array_filter/array_map chains with a typed, chainable collection API
• Building lazy, query-backed collections that only hit the database when iterated
• Applying reusable, storage-agnostic filter criteria across in-memory and persisted collections

Under The Hood

Architecture - The library centers on the Collection interface (src/Collection.php), extended by ReadableCollection for read-only access, with ArrayCollection (src/ArrayCollection.php) as the canonical in-memory implementation wrapping a native PHP array behind the interface’s methods. AbstractLazyCollection (src/AbstractLazyCollection.php) implements the same interface but defers to a doInitialize() template method, which is how Doctrine ORM’s PersistentCollection defers loading related entities until they’re accessed. Filtering is handled by a separate Criteria/Expr subsystem (src/Expr/, src/Criteria.php, src/ExpressionBuilder.php) that builds an expression tree independent of any storage backend, letting the same Criteria object filter an in-memory ArrayCollection or be translated into SQL by an ORM. Tech Stack - Pure PHP (100% of the codebase) targeting PHP 8.4+, with doctrine/deprecations for structured deprecation notices and symfony/polyfill-php86 as its only non-dev runtime dependencies; PHPStan (level-strict) and doctrine/coding-standard enforce static analysis and style in CI. Code Quality - The tests/ directory (PHPUnit 12) covers each collection method plus the Criteria/Expr matching logic with dedicated test classes; the public interfaces are fully typed (PHP 8 union/nullable types, psalm/phpstan template annotations for generics), and 109 contributors with 833 total commits indicate broad, sustained scrutiny of the codebase. API Design - Method names mirror familiar functional-collection vocabulary (map, filter, reduce, partition, matching) with a single Collection interface implemented consistently across in-memory and lazy variants, so consumers can swap an ArrayCollection for a lazy, database-backed one without changing call sites.