Easyadmin Filters Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require coolshop/easyadmin-filters-bundle
   

   Enable the bundle in config/bundles.php:

   Coolshop\EasyAdminFilters\CoolshopEasyAdminFiltersBundle::class => ['all' => true],
   

2. First Use Case Extend your existing EasyAdmin CRUD controller with AdminFilterableController:

   use Coolshop\EasyAdminFilters\Controller\AdminFilterableController;
   
   class UserCrudController extends AdminFilterableController
   {
       // Your existing CRUD logic
   }
   

3. Configuration Define filters in config/packages/easy_admin.yaml:

   easy_admin:
       User:
           list:
               filters: ['username', 'lastLogin']
               fields: ['username', 'firstName', 'lastName']
   

4. Verify Refresh the cache (php bin/console cache:clear) and check the EasyAdmin list view—filter inputs should now appear.

Implementation Patterns

Controller Integration

• Extending Base Controller Prefer extending AdminFilterableController for full functionality:

  class PostCrudController extends AdminFilterableController
  {
      public static function getEntityFqcn(): string
      {
          return Post::class;
      }
  }
  

• Trait Alternative Use the Filterable trait for partial integration (e.g., in existing controllers):

  use Coolshop\EasyAdminFilters\Controller\Traits\Filterable;
  
  class LegacyUserController
  {
      use Filterable;
      // ...
  }
  

Filter Configuration

• Dynamic Filters Override configureFilters() to dynamically set filters:

  protected function configureFilters(): array
  {
      return ['title', 'publishedAt']; // Overrides YAML config
  }
  

• Field-Specific Filters Use Doctrine types to auto-configure filters (e.g., date, string):

  filters:
      - { name: 'createdAt', type: 'date' }
      - { name: 'status', type: 'choice', options: { choices: ['active', 'inactive'] } }
  

Workflow Tips

• Filter Persistence Leverage Symfony’s Request to save filter state across paginations:

  $this->get('session')->set('easyadmin_filters', $this->getFilters());
  

• Reusable Filter Logic Create a base controller for shared filter configurations:

  abstract class BaseCrudController extends AdminFilterableController
  {
      protected function getDefaultFilters(): array
      {
          return ['isActive'];
      }
  }
  

Gotchas and Tips

Common Pitfalls

• Cache Invalidation After adding filters, clear the cache:

  php bin/console cache:clear --env=prod
  

  Symptom: Filters not appearing despite correct YAML.

• Field vs. Filter Mismatch Ensure filter fields exist in fields or properties; otherwise, EasyAdmin throws:

  Property [non_existent_field] does not exist on [App\Entity\User].
  

  Fix: Add the field to your entity or remove it from filters.

• Doctrine Type Conflicts Filters may fail for unsupported Doctrine types (e.g., json, array). Workaround: Use custom filter types or exclude such fields.

Debugging

• Filter Values Not Applying Check the generated SQL query for missing WHERE clauses. Use:

  $this->get('debug')->dump($this->getFilters());
  

  Tip: Enable Symfony’s profiler to inspect the request.

• YAML Parsing Errors Validate YAML syntax with:

  php bin/console debug:config easy_admin
  

  Symptom: Uncaught Symfony\Component\Config\Definition\Exception\InvalidConfigurationException.

Extension Points

• Custom Filter Types Extend the bundle’s filter system by implementing Coolshop\EasyAdminFilters\Filter\FilterInterface:

  class CustomStatusFilter implements FilterInterface
  {
      public function apply(QueryBuilder $qb, $field, $value)
      {
          $qb->andWhere("u.status = :status")->setParameter('status', $value);
      }
  }
  

  Register it in services.yaml:

  services:
      App\Filter\CustomStatusFilter:
          tags: [coolshop.easyadmin_filters.filter]
  

• Override Filter Templates Customize the filter UI by overriding the Twig template:

  # templates/easyadmin/filters/filter_widget.html.twig
  {{ include('CoolshopEasyAdminFilters::filter_widget.html.twig') }}
  

  Tip: Use {{ dump(_context) }} to inspect available variables.

Performance

• Avoid N+1 Queries Filters may trigger lazy-loading. Use fetch="EAGER" or DQL JOIN in configureQuery():

  protected function configureQuery(QueryBuilder $qb): void
  {
      $qb->leftJoin('u.relatedEntity', 're');
  }
  

• Indexed Database Fields Ensure filtered columns are indexed in the database for large datasets:

  /**
   * @ORM\Index(name="idx_username", columns={"username"})
   */