Dms Filter Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require dms/dms-filter-bundle
   

   Enable the bundle in config/bundles.php:

   DMS\Bundle\FilterBundle\DMSFilterBundle::class => ['all' => true],
   

2. First Use Case: Annotate an entity with basic filters (e.g., Trim, StripTags) to automatically sanitize form inputs:

   use DMS\Filter\Rules as Filter;
   
   class User {
       #[Filter\Trim]
       #[Filter\StripTags]
       public string $name;
   }
   

   The bundle will now auto-filter form submissions for this entity.

3. Where to Look First:

   • Annotations Reference (for available rules).
   • config/packages/dms_filter.yaml (for bundle configuration).
   • Symfony’s FormType classes (to see auto-filtering in action).

Implementation Patterns

1. Annotation-Based Filtering

• Workflow: Annotate entity properties with filters (e.g., #[Filter\Email], #[Filter\Numeric]). The bundle hooks into Symfony’s form system to apply these filters automatically during form submission.
• Example:

  #[Filter\Email]
  #[Filter\NotEmpty]
  public string $email;
  

  Result: Invalid emails or empty values trigger Symfony’s validation errors.

2. Manual Filtering

• Use Case: Filter data outside forms (e.g., API requests, CLI scripts).
• Pattern:

  use DMS\Filter\FilterManager;
  
  $filterManager = $container->get('dms.filter.inner.filter');
  $filteredData = $filterManager->filter($rawData, User::class);
  

• Tip: Pass the entity class to leverage its annotations dynamically.

3. Custom Rules

• Extend Existing Rules: Create a custom rule by implementing DMS\Filter\RuleInterface:

  class CustomRule implements RuleInterface {
      public function filter($value): ?string {
          return strtoupper($value);
      }
  }
  

• Register Rule: Add to services.yaml:

  services:
      App\Filter\CustomRule:
          tags: [dms.filter.rule]
  

• Use in Entity:

  #[Filter\CustomRule]
  public string $customField;
  

4. Form Integration

• Auto-Filtering: Enable/disable via config (auto_filter_forms: true/false).
• Manual Override: Disable filtering for a specific form:

  $builder->add('name', TextType::class, [
      'dms_filter' => false,
  ]);
  

5. Validation + Filtering

• Combine with Symfony’s validator for robust input handling:

  #[Assert\Length(min: 3)]
  #[Filter\Trim]
  public string $username;
  

Gotchas and Tips

Pitfalls

1. Circular Dependencies:

   • If filters modify data in a way that breaks validation (e.g., Trim removes required whitespace), validation may fail unexpectedly.
   • Fix: Test edge cases (e.g., #[Filter\Trim] #[Assert\NotBlank] with whitespace-only input).

2. Performance:

   • Applying many filters to large datasets (e.g., bulk API imports) can be slow.
   • Tip: Use manual filtering with a FilterManager for batch processing and disable auto-filtering in forms.

3. Annotation Caching:

   • Clear Symfony’s cache (php bin/console cache:clear) after adding new annotations or custom rules.

4. Symfony 6+ Compatibility:

   • The bundle uses annotations, which require symfony/property-access and symfony/property-info. Ensure your composer.json includes:

     "require": {
         "symfony/property-access": "^6.0",
         "symfony/property-info": "^6.0"
     }
     

Debugging Tips

1. Log Filtered Values:

   • Temporarily add a #[Filter\CustomRule] with logging to inspect filtered data:

     class DebugRule implements RuleInterface {
         public function filter($value): ?string {
             error_log("Raw: $value");
             return $value;
         }
     }
     

2. Disable Auto-Filtering:

   • Set auto_filter_forms: false in config/packages/dms_filter.yaml to isolate issues.

3. Check Service Availability:

   • Ensure dms.filter.inner.filter is autowired correctly. If not, verify the bundle is enabled and dependencies are installed.

Extension Points

1. Dynamic Rule Application:

   • Override the FilterManager to conditionally apply rules:

     $filterManager->addRule($property, new CustomRule(), $entity);
     

2. Rule Prioritization:

   • Rules are applied in the order they’re annotated. Use #[Filter\Order] to customize:

     #[Filter\Order(10)] // Lower numbers run first
     #[Filter\Trim]
     public string $field;
     

3. Non-Entity Filtering:

   • Use the FilterManager to filter arrays or objects without annotations:

     $filterManager->filter($data, null, [
         'field' => [new Trim(), new StripTags()]
     ]);
     

Configuration Quirks

• Case Sensitivity:

  • Annotations are case-sensitive (e.g., #[Filter\Trim] vs. #[Filter\trim]). Use the exact class name from the rules list.

• Null Handling:

  • Some rules (e.g., #[Filter\Email]) may throw exceptions on null values. Use #[Filter\Default] to provide fallbacks:

    #[Filter\Default('default@example.com')]
    #[Filter\Email]
    public ?string $email;