Doctrine Filters Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require business-decision/doctrine-filters-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Doctrine\Filters\DoctrineFiltersBundle::class => ['all' => true],
   ];
   

2. Enable Filters Enable the bundle in config/packages/doctrine.yaml:

   doctrine:
       orm:
           filters:
               softdeleteable:
                   class: Doctrine\ORM\Mapping\ClassMetadata
                   enabled: true
   

3. First Use Case Apply a filter to an entity (e.g., SoftDeleteableFilter):

   use Doctrine\ORM\Mapping as ORM;
   
   

/**

• @ORM\Entity(repositoryClass="App\Repository\YourEntityRepository")
• @ORM\HasLifecycleCallbacks / class YourEntity { // ... /*
  • @ORM\Column(type="boolean")
  • @ORM\Filter("softdeleteable", expression="entity.deleted = false OR entity.deleted IS NULL") */ private $deleted; // ... }

Implementation Patterns

Common Workflows

1. Dynamic Filter Application Enable/disable filters programmatically:

   $filter = $entityManager->getFilters()->enable('softdeleteable');
   $results = $entityManager->getRepository(YourEntity::class)->findAll();
   $filter->disable(); // Cleanup
   

2. Custom Filter Creation Extend Doctrine\ORM\Mapping\ClassMetadataFilter:

   namespace App\Filter;
   
   use Doctrine\ORM\Mapping\ClassMetadata;
   use Doctrine\ORM\Mapping\ClassMetadataFilter;
   
   class CustomFilter extends ClassMetadataFilter
   {
       public function matchClassMetadata(ClassMetadata $classMetadata): bool
       {
           return $classMetadata->getName() === YourEntity::class;
       }
   }
   

3. QueryBuilder Integration Use filters in repositories:

   public function findActiveEntities()
   {
       $queryBuilder = $this->createQueryBuilder('e');
       $queryBuilder->andWhere('e.deleted = false');
       return $queryBuilder->getQuery()->getResult();
   }
   

4. Parameterized Filters Pass runtime values:

   $filter = $entityManager->getFilters()->get('softdeleteable');
   $filter->setParameter('deleted', false);
   

Integration Tips

• Leverage Events: Use filters.loaded and filters.enabled events for side effects.
• Symfony Forms: Bind filters to form fields (e.g., checkboxes for soft-delete toggles).
• API Layer: Expose filter states in API responses for client-side control.
• Doctrine Extensions: Combine with Stof\DoctrineExtensionsBundle for advanced filtering (e.g., Sluggable, Timestampable).

Gotchas and Tips

Pitfalls

1. Filter Order Matters Filters are applied in the order they are registered. Use setPriority() to control execution order:

   $filter->setPriority(10); // Lower = earlier
   

2. Memory Leaks Forgetting to disable filters can cause performance issues. Use a try-finally block or a decorator pattern to ensure cleanup.

3. Caching Conflicts Filters bypass query caching. Disable caching for filtered queries if needed:

   $query->setCacheable(false);
   

4. Entity Inheritance Filters on parent entities may unintentionally affect child entities. Use matchClassMetadata() carefully.

Debugging

• Enable SQL Logging Temporarily enable SQL logging in config/packages/dev/doctrine.yaml:

  doctrine:
      dbal:
          logging: true
          profiling: true
  

  Check var/log/dev.log for generated queries.

• Filter Dump Inspect active filters:

  $filters = $entityManager->getFilters()->getEnabledFilters();
  print_r($filters);
  

Extension Points

1. Custom Filter Parameters Extend Doctrine\ORM\Mapping\ClassMetadataFilter to support dynamic parameters:

   public function addFilterParameter($name, $value)
   {
       $this->parameters[$name] = $value;
   }
   

2. Filter Groups Group filters for bulk enable/disable:

   $group = ['softdeleteable', 'archivable'];
   foreach ($group as $filterName) {
       $entityManager->getFilters()->enable($filterName);
   }
   

3. Event Subscribers Listen to filters.loaded to modify filter behavior:

   namespace App\EventSubscriber;
   
   use Doctrine\ORM\Event\FiltersEventArgs;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class FilterSubscriber implements EventSubscriberInterface
   {
       public function onFiltersLoaded(FiltersEventArgs $args)
       {
           $filters = $args->getFilters();
           // Modify filters here
       }
   }
   

4. Doctrine Event Listeners Attach listeners to filter lifecycle events:

   $eventManager->addEventListener(
       \Doctrine\ORM\Events::LOAD_CLASS_METADATA,
       [$filter, 'loadClassMetadata']
   );