Collections Laravel Package

Getting Started

Start by installing the package via Composer: composer require doctrine/collections. The core interface is Doctrine\Common\Collections\Collection, with ArrayCollection as the primary implementation. The simplest use case is replacing native PHP arrays with ArrayCollection for object collections that require iteration, filtering, or sorting—e.g., managing a set of entities in domain models or value objects. The Collection::fromArray() factory method provides an easy migration path from arrays.

Implementation Patterns

• Domain Model Integrity: Wrap entity collections (e.g., OrderItem[]) in ArrayCollection to enforce immutability or controlled mutation via methods like add(), removeElement(), and remove().
• Deferred Filtering & Sorting: Use Criteria with Matching expressions (ExpressionBuilder) to build SQL-like filters and orderings before materializing results—especially useful in layers before database queries (e.g., in services or VO layers). Example:

  $matching = Matching::expr()->eq('status', 'active');
  $filtered = $users->matching(Matching::create($matching, Matching::orderBy(['name' => Order::ASC])));
  

• Lazy Loading Proxies: Extend AbstractLazyCollection when deferring expensive collection population until iteration (e.g., lazy-loaded related data).
• Read-Only Protection: Leverage ReadableCollection (or ArrayCollection in 3.x) to expose internal collections safely via getters—ensuring callers can’t mutate internal state directly.

Gotchas and Tips

• BC Break in 3.0+: Classes are final, ReadablesCollection now extends Selectable, and Collection::add() returns void (not true). Ensure tests and extension points are reviewed.
• Type Safety: PHP 8.4+ is now required (3.0); prefer native types over docblocks for IDE and static analysis support. Always verify return types—e.g., filter() returns a new collection, not in-place modification.
• ExpressionBuilder Limitations: Complex conditions requiring OR logic must be composed via CompositeExpression::TYPE_OR(). NOT expressions (added in 2.1.0) work but only for equality conditions—not arbitrary predicates.
• Key Preservation: Criteria with orderBy() and setMaxResults() may lose keys; use preserveKeys: true in toArray() or avoid key-dependent logic when slicing.
• Serialization Caveats: By default, ArrayCollection serializes its internal array—custom logic may be needed if internal state (e.g., hydrated proxies) must be preserved. Always test across cache layers.
• Debugging Tip: Enable strict typing + static analysis ( Psalm/PHPStan )—collection type inference is strong, but mismatched closures (e.g., filter() with key/value arity mismatch) can cause subtle issues.