Filter Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require aygon/filter-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Aygon\FilterBundle\AygonFilterBundle::class => ['all' => true],
   ];
   

2. Basic Usage Register a filter in a form type:

   use Aygon\FilterBundle\Form\FilterType;
   
   class MyFormType extends AbstractType {
       public function buildForm(FormBuilderInterface $builder, array $options) {
           $builder
               ->add('fieldName', TextType::class)
               ->add('filter', FilterType::class, [
                   'mapped' => false,
                   'filters' => [
                       'trim' => ['enabled' => true],
                       'lowercase' => ['enabled' => true],
                   ],
               ]);
       }
   }
   

3. First Use Case Apply filters to a form submission:

   $form = $this->createForm(MyFormType::class);
   $form->handleRequest($request);
   
   if ($form->isSubmitted() && $form->isValid()) {
       $filteredValue = $form->get('filter')->getData(); // Processed value
   }
   

Implementation Patterns

Common Workflows

1. Dynamic Filter Application Use FilterType with dynamic filter configurations:

   $builder->add('filter', FilterType::class, [
       'filters' => [
           'trim' => ['enabled' => $isTrimEnabled],
           'custom_filter' => ['enabled' => true, 'param' => 'value'],
       ],
   ]);
   

2. Reusable Filter Groups Define filter groups in a service or config:

   # config/packages/aygon_filter.yaml
   aygon_filter:
       default_filters:
           text: ['trim', 'lowercase']
           numeric: ['trim', 'floatval']
   

   Apply via:

   $builder->add('filter', FilterType::class, [
       'filters' => $this->get('aygon_filter.config')->get('default_filters.text'),
   ]);
   

3. Integration with Form Events Modify filters dynamically via PRE_SUBMIT:

   $builder->addEventListener(FormEvents::PRE_SUBMIT, function (FormEvent $event) {
       $data = $event->getData();
       $event->getForm()->get('filter')->setFilters([
           'custom' => ['enabled' => !empty($data['enable_custom_filter'])],
       ]);
   });
   

4. Custom Filters Extend Aygon\FilterBundle\Filter\AbstractFilter:

   class MyCustomFilter extends AbstractFilter {
       public function apply($value) {
           return str_replace('foo', 'bar', $value);
       }
   }
   

   Register in services:

   services:
       app.filter.my_custom:
           class: App\Filter\MyCustomFilter
           tags: { name: aygon_filter.filter }
   

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch The bundle is Symfony 2.1-only (not compatible with 2.2+). Use a fork or alternative (e.g., stof/doctrine-extensions) for newer versions.

2. Filter Order Matters Filters execute in declaration order. Reorder for expected behavior:

   // 'trim' runs before 'lowercase'
   $builder->add('filter', FilterType::class, [
       'filters' => ['trim', 'lowercase'],
   ]);
   

3. Non-Mapped Fields FilterType must have mapped: false to avoid validation errors or data binding issues.

4. Missing Documentation The package lacks examples for advanced use (e.g., async filters, custom validation). Refer to src/Filter/ for built-in filters.

Debugging Tips

• Check Applied Filters Dump the processed data:

  var_dump($form->get('filter')->getData());
  

• Enable Debug Mode Set AYGON_FILTER_DEBUG: true in .env to log filter execution.

Extension Points

1. Override Default Filters Replace built-in filters via DI:

   services:
       aygon_filter.filter.trim:
           class: App\Filter\CustomTrimFilter
           tags: { name: aygon_filter.filter, alias: trim }
   

2. Add Filter Parameters Pass runtime params:

   $builder->add('filter', FilterType::class, [
       'filters' => [
           'custom' => ['enabled' => true, 'param' => $dynamicValue],
       ],
   ]);
   

3. Integrate with Validation Combine with Symfony’s Constraints:

   $builder->add('field', TextType::class, [
       'constraints' => [
           new NotBlank(),
           new Length(['min' => 3]),
       ],
   ]);
   $builder->add('filter', FilterType::class, ['filters' => ['trim']]);