Query Builder Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require filament/query-builder
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Filament\QueryBuilder\QueryBuilderServiceProvider"
   

2. Basic Usage Add the QueryBuilder widget to a Filament resource:

   use Filament\Forms\Components\QueryBuilder;
   
   public static function form(Form $form): Form
   {
       return $form
           ->schema([
               QueryBuilder::make('users')
                   ->label('Search Users')
                   ->columns(3),
           ]);
   }
   

3. First Use Case

   • Filtering a table: Replace a Select or MultiSelect with QueryBuilder for dynamic, multi-criteria filtering.
   • Example:

     QueryBuilder::make('posts')
         ->label('Filter Posts')
         ->columns(2)
         ->query(fn (Builder $query) => $query->where('published', true))
     

Implementation Patterns

Common Workflows

1. Dynamic Query Building Use modifyQueryUsing() to inject logic:

   QueryBuilder::make('orders')
       ->modifyQueryUsing(fn (Builder $query) => $query->where('status', '!=', 'cancelled'))
   

2. Customizing Columns Override default column behavior:

   QueryBuilder::make('products')
       ->columns(4)
       ->column('price', fn (Column $column) => $column->numeric())
   

3. Integration with Filament Tables Use QueryBuilder in a Table for real-time filtering:

   public static function table(Table $table): Table
   {
       return $table
           ->columns([
               // ...
           ])
           ->filters([
               QueryBuilder::make('users')
                   ->label('Advanced Search')
                   ->columns(2),
           ]);
   }
   

4. Reusing Query Builders Create a reusable trait or class:

   class UserQueryBuilder extends QueryBuilder
   {
       public static function make(): static
       {
           return parent::make('users')
               ->label('User Search')
               ->columns(3)
               ->searchable(['name', 'email']);
       }
   }
   

5. Async or API Usage For API endpoints, use QueryBuilder with Filament\Forms\Components\Hidden to store filters:

   QueryBuilder::make('tasks')
       ->hidden()
       ->dehydrateStateUsing(fn (array $state) => json_encode($state))
   

Gotchas and Tips

Pitfalls

1. Performance with Large Datasets

   • Issue: Complex queries on large tables may cause timeouts.
   • Fix: Use ->limit(100) or ->with(['relationship']) sparingly. Consider caching or indexing.

2. Relationship Pitfalls

   • Issue: Nested relationships may not render correctly.
   • Fix: Explicitly define relationships in ->relationships():

     QueryBuilder::make('posts')
         ->relationship('author', 'authors')
     

3. State Persistence

   • Issue: Filters reset on form reload.
   • Fix: Use ->persistState() or store in session manually.

4. CSRF/Validation Conflicts

   • Issue: Hidden QueryBuilder fields may trigger validation errors.
   • Fix: Exclude from validation:

     QueryBuilder::make('users')
         ->hidden()
         ->rules([])
     

Debugging Tips

• Log Queries: Enable Laravel query logging to inspect generated SQL:

  QueryBuilder::make('orders')
      ->modifyQueryUsing(fn (Builder $query) => $query->toSql())
  

• Check Config: Verify config/filament-query-builder.php for overrides (e.g., default columns).

Extension Points

1. Custom Columns Extend Filament\QueryBuilder\Columns\Column for new column types:

   class RangeColumn extends Column
   {
       protected string $view = 'filament-query-builder::columns.range';
   }
   

2. Override Views Publish and modify views:

   php artisan vendor:publish --tag="filament-query-builder-views"
   

3. Hooks Use registered and registeredColumn events for dynamic modifications:

   QueryBuilder::make('tasks')
       ->registerUsing(fn (QueryBuilder $component) => $component->modifyQueryUsing(...))