Common Laravel Package

Getting Started

Start by requiring the package via Composer:

composer require doctrine/common

Despite its age (last release 2025-01-01 suggests future-dated), doctrine/common is largely stable and backward-compatible — many of its components are now decoupled or rehomed in newer packages (e.g., doctrine/persistence, doctrine/deprecations).
First use case: if you’re building a Doctrine-based application (e.g., ORM or DBAL), you likely already depend on it transitively, but explicitly requiring it allows you to use its foundational utilities (e.g., Doctrine\Common\Collections\Collection) directly.

Implementation Patterns

• Collection Handling: Use Doctrine\Common\Collections\Collection and Expr for in-memory filtering:

  use Doctrine\Common\Collections\Collection;
  use Doctrine\Common\Collections\Expr\Expr;
  
  $users = new Collection($userArray);
  $activeAdmins = $users->matching(
    Expr::andX(
      Expr::eq('isActive', true),
      Expr::eq('role', 'admin')
    )
  );
  

• Event Dispatcher: Integrate Doctrine’s event system (via Doctrine\Common\EventManager) to hook into custom lifecycle events:

  $em = new EventManager();
  $em->addEventListener('user.created', new UserWelcomeListener());
  

• Metadata Mapping: Leverage Doctrine\Common\Annotations\Reader for custom annotation-driven configuration in your own libraries (e.g., command decorators, config attributes).
• Proxy Generation: While mostly internal, use Proxy\ProxyFactory only when implementing custom object hydration or lazy-loading strategies.

Gotchas and Tips

• Deprecation & Decoupling: Since ~v2.13, core features have been split:
  • Annotations → doctrine/annotations
  • Cache → doctrine/cache (deprecated; use PSR-6/PSR-16 instead)
  • Persistence → doctrine/persistence
    Always verify which package you’re actually using — importing from Doctrine\Common for cache/annotations may cause class-not-found errors.
• Type Safety: Prefer Doctrine\Common\Collections\ArrayCollection over plain arrays for better IDE inference and typehinting (Collection interface).
• EventListener Signature: The event system uses Doctrine\Common\EventSubscriber — ensure your subscribers implement getSubscribedEvents() and use consistent naming (e.g., onUserPersist, not onUserPersist()).
• Proxies & Autoloading: Custom proxy generation requires correct autoloading setup — ensure doctrine/persistence is also present for compatibility.
• Debugging: Enable doctrine/deprecations via handle() to catch subtle breaking changes in underlying Doctrine APIs.