# spiriitlabs/form-filter-bundle architecture

> Architecture diagram of the GitHub repository spiriitlabs/form-filter-bundle, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/spiriitlabs/form-filter-bundle
- Repository: https://github.com/spiriitlabs/form-filter-bundle

## Overview

##### Project Type and Purpose
- This is a Symfony bundle, originally the LexikFormFilterBundle, that offers form filter types. Its main responsibility is to let developers create specialized Symfony form types (e.g., TextFilterType, NumberFilterType, etc.) that can then be used to update a Doctrine query builder with filtering conditions.
- The README emphasizes the bundle’s role in filtering an entity by using the form system and then translating these filters into query builder conditions. It also illustrates usage in controllers and details configuration and customization aspects.

##### File Structure
- Top-level directories such as “DependencyInjection”, “Event”, and “Filter” indicate clear separations of concerns:
- The DependencyInjection directory handles configuration, compiler passes, and the bundle’s extension for loading services.
- The Event directory contains custom events, listeners, and subscribers that hook into the filtering lifecycle (e.g. before and after applying filter conditions).
- The Filter directory is the core of the bundle. It includes subdirectories for conditions and data extractors, where you find condition builders, expression builders for Doctrine (both ORM and DBAL), and actual filter builders/updaters.
- Additional directories like “Resources” (holding configuration XML files, Twig templates, translations, and documentation) show integration with the Symfony framework.
- The “Tests” directory provides unit and integration tests that validate the components, ensuring the bundle’s functionality and reliability.
- Configuration files (composer.json, phpunit.xml.dist, etc.) and build/CI configurations (.github/workflows) indicate modern development practices.

##### Main Components and their Relationships
- Dependency Injection Component:
- Handles service definitions, configuration (e.g., “Resources/config/services.xml”), and compiler passes (in DependencyInjection/Compiler).
- Integrates with Symfony’s container to wire form filter types, custom services, and configuration parameters.
- Event Component:
- Contains custom events (e.g., ApplyFilterConditionEvent, PrepareEvent) that trigger during the lifecycle of form filtering.
- Includes listeners and subscribers that respond to these events to modify query builders.
- Filter Component:
- Houses multiple aspects:
- Condition: This sub-module builds conditions (e.g., ConditionBuilder, ConditionNode) that define filtering logic.
- Data Extraction: Responsible for extracting and processing form input data using different extraction methods.
- Doctrine Integration: Classes dedicated to adapting filters to Doctrine’s ORM and DBAL query builders (e.g., ORMExpressionBuilder, DBALQuery).
- Form Integration: Extends Symfony form types, adding custom filter functionality (see Filter/Form and provided types like TextFilterType, NumberFilterType, etc.).
- Resources:
- Contains configuration files for Doctrine and forms, Twig templates for rendering, and translations/documentation that guide usage and integration.
- Tests:
- Ensures components behave as expected; they verify DI configuration, filter building, and interactions with Doctrine query builders.

##### Architectural Patterns and Design Principles
- Modular Separation: Each subdirectory reflects a well-separated concern (DI, Events, Filtering logic, Testing).
- Event-driven design: The bundle leverages custom events and subscribers/listeners to allow extensibility and decoupling.
- Integration with Symfony Framework: Follows Symfony conventions (service configuration, form type extensions, configuration files).
- Extensibility and Customization: Developers are encouraged to extend built-in types or create custom ones, especially by tapping into the event system.

##### Specific Elements
- Form creation -> handling (via Filter/Form types) -> query building (via Filter/Doctrine classes) -> final query execution.
- Event dispatch during these interactions.
- For core logic (filters, events, DI) use a consistent style.
- For configuration and resources (templates, translation, XML config files), use a complementary style.

- DI loads service definitions and configurations.
- The Filter module processes form data and builds conditions.
- Events are dispatched and caught by specific listeners/subscribers which influence the filter update process.
- Doctrine integration modules receive these conditions to modify query builders.
- Components are clearly annotated with labels and technology references (e.g., Symfony, Doctrine).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Application Form Submission"]:::symfony

    subgraph "Configuration and Setup"
        DI["DI Container / Service Config"]:::bundle
        R["Resources Config & Templates"]:::resources
    end

    subgraph "Bundle Modules"
        FFT["Form Filter Types"]:::bundle
        DE["Data Extraction"]:::bundle
        FC["Filter Condition Builder"]:::bundle
        DI2["Doctrine Integration Adapter"]:::external
        E["Event Listeners & Subscribers"]:::bundle
    end

    T["Tests"]:::test

    A -->|"triggers"| FFT
    DI -->|"configures"| FFT
    R -->|"loads_config"| DI
    R -->|"provides_templates"| FFT
    FFT -->|"extracts_data"| DE
    FFT -->|"initiates_condition"| FC
    FC -->|"builds_query"| DI2
    FC -->|"dispatches_event"| E
    DI -->|"registers_listeners"| E
    DI -->|"configures_doctrine"| DI2

    T -->|"tests_DI"| DI
    T -->|"tests_Form_Filter"| FFT
    T -->|"tests_Filter_Conditions"| FC
    T -->|"tests_Event_Handling"| E
    T -->|"tests_Doctrine"| DI2

    click DI "https://github.com/spiriitlabs/form-filter-bundle/tree/master/DependencyInjection/"
    click E "https://github.com/spiriitlabs/form-filter-bundle/tree/master/Event/"
    click FC "https://github.com/spiriitlabs/form-filter-bundle/tree/master/Filter/Condition/"
    click DE "https://github.com/spiriitlabs/form-filter-bundle/tree/master/Filter/DataExtractor/"
    click DI2 "https://github.com/spiriitlabs/form-filter-bundle/tree/master/Filter/Doctrine/"
    click FFT "https://github.com/spiriitlabs/form-filter-bundle/tree/master/Filter/Form/Type/"
    click R "https://github.com/spiriitlabs/form-filter-bundle/tree/master/Resources/"
    click T "https://github.com/spiriitlabs/form-filter-bundle/tree/master/Tests/"

    classDef symfony fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef bundle fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#ffeeba,stroke:#856404,stroke-width:2px;
    classDef resources fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef test fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
