Module Doctrine Laravel Package

Getting Started

This package, Codeception's Doctrine Module, enables seamless interaction with Doctrine ORM entities in Codeception tests. To get started:

1. Installation: Require the package via Composer:

   composer require codeception/module-doctrine
   

2. Configuration: Add the module to your codeception.yml under modules:

   modules:
     enabled:
       - Doctrine:
           dsn: 'sqlite:///:memory:'  # Replace with your DB connection
           entityManager: '@doctrine.orm.entity_manager'  # Symfony DI container key (if applicable)
   

3. First Use Case: Use the module to create, fetch, or delete entities in tests:

   $this->haveInDatabase('App\Entity\User', ['id' => 1, 'name' => 'John']);
   $user = $this->grabFromDatabase('App\Entity\User', ['id' => 1]);
   $this->seeRecord('App\Entity\User', ['name' => 'John']);
   

Implementation Patterns

Core Workflows

1. Entity Management:

   • Use haveInDatabase() to seed test data before tests.
   • Use seeRecord()/dontSeeRecord() for assertions.
   • Use deleteFromDatabase() to clean up after tests.

2. Lazy Loading & Performance:

   • The module now supports native lazy objects (PR #45) when using Symfony 8+, reducing overhead for large datasets. No manual configuration is needed—it auto-detects compatibility.

3. Dependency Injection:

   • For Symfony projects, inject the entityManager via DI container (e.g., @doctrine.orm.entity_manager). The module will use this instead of creating its own connection.

4. Complex Queries:

   • Use grabFromDatabase() with DQL or Criteria API for advanced queries:

     $users = $this->grabFromDatabase('App\Entity\User', 'u WHERE u.age > :age', ['age' => 18]);
     

Integration Tips

• Laravel: Use the db.connection config key to specify your Laravel DB connection:

  modules:
    Doctrine:
      db: 'mysql'
      entityManager: null  # Laravel uses its own EM
  

• Test Isolation: Combine with Db module for transactions:

  modules:
    enabled:
      - Db
      - Doctrine
  

  Then wrap tests in transactions to avoid DB pollution.

Gotchas and Tips

Breaking Changes (v3.3.0)

• PHP 8.1 Dropped: This release requires PHP 8.2+. Update your project or pin to 3.2.x if stuck on PHP 8.1.
• Reflection Workarounds Removed: PR #44 removes Reflection*::setAccessible() calls, which may affect custom Doctrine extensions relying on private property access. Test thoroughly if you extend Doctrine.

Debugging Tips

1. Lazy Loading Issues:

   • If tests fail with lazy-loading errors (e.g., Proxy __load()), ensure your Symfony kernel is bootstrapped or use warmup() in tests:

     $this->getModule('Doctrine')->getEntityManager()->getConnection()->getWrappedConnection()->getNativeConnection()->close();
     

   • For non-Symfony projects, manually enable lazy loading via config:

     Doctrine:
       useLazyObjects: true
     

2. Deprecation Warnings:

   • If using doctrine/collections:2.4, suppress warnings by updating to 2.5+ or configure the module to ignore them:

     Doctrine:
       ignoreDeprecations: true
     

3. Object ID Fixes:

   • PR #47 resolves issues with object IDs in assertions. If you rely on custom ID fields, verify your tests still work:

     $this->seeRecord('App\Entity\User', ['customId' => 'abc123']);
     

Extension Points

• Custom Repositories: Override the default repository logic by binding a custom repository to the module:

  $this->getModule('Doctrine')->setRepository('App\Entity\User', CustomUserRepository::class);
  

• Event Subscribers: Attach Doctrine events (e.g., postPersist) via the module’s getEntityManager():

  $em = $this->getModule('Doctrine')->getEntityManager();
  $em->getEventManager()->addEventSubscriber(new CustomSubscriber());
  

• Custom DQL: Extend the module’s DQL builder for project-specific needs by subclassing and overriding buildQuery() in a custom module.

Performance Quirks

• Memory Usage: Lazy objects (enabled by default in Symfony 8+) reduce memory but may cause N+1 queries. Use fetchAll() for bulk operations if needed:

  $users = $this->grabFromDatabase('App\Entity\User', [], [], ['fetch' => 'EAGER']);
  

• CI Failures: If tests fail in CI with Symfony 8+, explicitly enable lazy objects:

  Doctrine:
    useLazyObjects: true