Doctrine Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation via Composer (if using Satis):

   composer require awaresoft/doctrine-bundle
   

   Note: Due to symlinking requirements, follow the README’s local setup guide if modifying the bundle.

2. Enable the Bundle in config/bundles.php:

   return [
       // ...
       Awaresoft\DoctrineBundle\AwaresoftDoctrineBundle::class => ['all' => true],
   ];
   

3. First Use Case:

   • Custom Doctrine Events: Extend Doctrine lifecycle events (e.g., prePersist, postLoad) without writing repetitive listeners.
   • Example: Override EntityListener in your entity:

     use Awaresoft\DoctrineBundle\Event\LifecycleEvent;
     use Doctrine\ORM\Mapping as ORM;
     
     #[ORM\Entity]
     class User
     {
         #[LifecycleEvent('prePersist')]
         public function setDefaultRole()
         {
             $this->role = 'user'; // Custom logic before save
         }
     }
     

Implementation Patterns

1. Event-Driven Workflows

• Pattern: Replace traditional Doctrine listeners with annotations or YAML configs.

  # config/packages/awaresoft_doctrine.yaml
  awaresoft_doctrine:
      listeners:
          App\Entity\User:
              prePersist: ['setDefaultRole']
              postLoad:   ['logEntityLoad']
  

• Integration Tip: Use for auditing, soft deletes, or dynamic field population.

2. Repository Extensions

• Pattern: Extend base repositories with shared methods.

  use Awaresoft\DoctrineBundle\Repository\AbstractRepository;
  
  class UserRepository extends AbstractRepository
  {
      public function findActiveUsers()
      {
          return $this->createQueryBuilder('u')
              ->where('u.isActive = :active')
              ->setParameter('active', true)
              ->getQuery()
              ->getResult();
      }
  }
  

• Workflow: Centralize CRUD logic (e.g., findByStatus) across projects.

3. Query Builder Helpers

• Pattern: Reuse common query fragments.

  use Awaresoft\DoctrineBundle\Query\QueryHelper;
  
  $qb = $entityManager->getRepository(User::class)->createQueryBuilder('u');
  $qb->andWhere(QueryHelper::isActive('u'));
  

4. Symfony Integration

• Pattern: Tie Doctrine events to Symfony services.

  // src/EventListener/UserListener.php
  use Awaresoft\DoctrineBundle\Event\LifecycleEventArgs;
  
  class UserListener
  {
      public function onPrePersist(LifecycleEventArgs $args)
      {
          $user = $args->getEntity();
          $user->setLastLogin(new \DateTime());
      }
  }
  

• Register in services.yaml:

  services:
      App\EventListener\UserListener:
          tags:
              - { name: 'awaresoft_doctrine.listener', event: 'prePersist', entity: 'App\Entity\User' }
  

Gotchas and Tips

Pitfalls

1. Symlinking Issues:

   • If modifying the bundle, ensure /src/Awaresoft is symlinked correctly. Clear cache after changes:

     php bin/console cache:clear
     

   • Debug Tip: Check composer.json for missing autoload_psr4 entries.

2. Event Priority Conflicts:

   • Explicitly define listener order in awaresoft_doctrine.yaml:

     listeners:
         App\Entity\User:
             prePersist:
                 - ['setDefaultRole', 10]  # Lower number = higher priority
                 - ['logCreation', 20]
     

3. FakerBundle Dependency:

   • The bundle requires willdurand/faker-bundle. Install it if using test data generation:

     composer require willdurand/faker-bundle
     

Debugging

• Enable Doctrine Debugging:

  # config/packages/dev/doctrine.yaml
  doctrine:
      dbal:
          logging: true
          profiling: true
  

• Check Event Firing: Use Symfony’s profiler (/profiler) to verify events trigger as expected.

Extension Points

1. Custom Event Subscribers:

   • Implement Awaresoft\DoctrineBundle\EventSubscriber\EventSubscriberInterface for cross-cutting concerns (e.g., logging, caching).

2. Query DSL:

   • Extend QueryHelper to add project-specific conditions:

     namespace App\Doctrine\Query;
     use Awaresoft\DoctrineBundle\Query\QueryHelper as BaseQueryHelper;
     
     class QueryHelper extends BaseQueryHelper
     {
         public static function isVerified($alias)
         {
             return "$alias.verified = true";
         }
     }
     

3. Configuration Overrides:

   • Override default bundle configs in config/packages/awaresoft_doctrine.yaml:

     awaresoft_doctrine:
         default_listener_priority: 0  # Adjust globally
         query_helpers:
             - App\Doctrine\Query\QueryHelper
     

Performance Tips

• Batch Processing: Use Awaresoft\DoctrineBundle\Batch\BatchProcessor for bulk operations:

  $processor = new BatchProcessor($entityManager, User::class);
  $processor->process($users, 50); // 50 entities per batch
  

• Avoid N+1 Queries: Leverage QueryHelper::join() for eager-loading:

  $qb->addSelect('u.profile')
     ->leftJoin('u.profile', 'p')
     ->where(QueryHelper::join('u', 'p', 'p.isActive = true'));