Query Builder Laravel Package

Getting Started

First Steps

1. Installation

   composer require act-training/query-builder
   

   Publish the config file (if available) with:

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

2. Basic Usage Import the package in your controller/service:

   use ActTraining\QueryBuilder\QueryBuilder;
   use App\Models\User;
   use ActTraining\QueryBuilder\ReportBuilder; // New for reporting features
   

3. First Query

   $users = QueryBuilder::for(User::class)
       ->where('active', true)
       ->orderBy('name')
       ->get();
   

4. ReportBuilder Usage (New)

   $report = new ReportBuilder(User::class);
   $report->columns(['id', 'name', 'email']); // Now with searchable column labels
   return view('reports.users', compact('report'));
   

5. Key Files to Review

   • config/query-builder.php (if published)
   • src/QueryBuilder.php (core class)
   • src/Traits/ (extension traits)
   • resources/js/column-search.js (new Alpine.js component)
   • src/ReportBuilder.php (new reporting class)

Implementation Patterns

Core Workflows

1. Dynamic Query Construction

$query = QueryBuilder::for(User::class)
    ->whereLike('name', request('search'))
    ->whereIn('role_id', request('roles', []))
    ->orderBy(request('sort', 'name'))
    ->paginate(request('per_page', 15));

2. ReportBuilder with Column Search (New)

// In your controller
$report = new ReportBuilder(User::class);
$report->columns([
    'id' => 'ID',
    'name' => 'Full Name',
    'email' => 'Email Address',
    'created_at' => 'Registration Date'
]);
// Column labels are now searchable via Alpine.js
return view('reports.users', compact('report'));

3. Customizing ReportBuilder Search

// Disable column search (default is enabled)
$report = new ReportBuilder(User::class);
$report->enableColumnSearch = false; // New property

4. Reusable Query Scopes

// app/Models/User.php
public function scopeActive($query)
{
    return $query->where('active', true);
}

// Usage
$query = QueryBuilder::for(User::class)->active()->get();

5. API Filtering

$filters = request()->input('filters', []);
$query = QueryBuilder::for(User::class);

foreach ($filters as $field => $value) {
    if (str_ends_with($field, '_like')) {
        $query->whereLike(str_replace('_like', '', $field), $value);
    }
}

Integration Tips

Laravel Service Providers

public function boot()
{
    QueryBuilder::extend(function ($builder) {
        $builder->macro('customScope', function ($builder) {
            return $builder->where('custom_field', 'value');
        });
    });
}

ReportBuilder Blade Integration

<x-query-builder::report-builder :report="$report" />
<!-- New component with built-in column search -->

Alpine.js Column Search Customization

// resources/js/column-search.js
document.addEventListener('alpine:init', () => {
    Alpine.data('columnSearch', () => ({
        init() {
            this.$watch('query', debounce(() => {
                // Custom search logic if needed
            }, 300));
        }
    }));
});

Testing ReportBuilder

public function test_report_builder_column_search()
{
    $report = new ReportBuilder(User::class);
    $report->columns(['name' => 'Full Name']);

    $view = blade()->render("reports.users", ['report' => $report]);
    $this->assertStringContainsString('x-data="columnSearch()"', $view);
}

Gotchas and Tips

Pitfalls

1. ReportBuilder Column Labels

• Issue: Column search matches against labels, not keys. Ensure descriptive labels are set.
• Fix: Explicitly define labels:

  $report->columns([
      'id' => 'User ID', // Searchable label
      'name' => 'Full Name'
  ]);
  

2. Alpine.js Conflicts

• Issue: Column search may conflict with existing Alpine.js instances.
• Fix: Use unique Alpine.js IDs:

  <x-query-builder::report-builder :report="$report" id="user-report-search" />
  

3. Performance with Large Columns

• Issue: Searching 100+ columns may impact UI performance.
• Fix: Disable search for large reports:

  $report->enableColumnSearch = false;
  

4. Dynamic Column Updates

• Issue: Column search doesn't update if columns change after initialization.
• Fix: Reinitialize Alpine.js or use Alpine.store() for shared state.

Debugging

1. ReportBuilder Debugging

$report = new ReportBuilder(User::class);
$report->columns(['name' => 'Full Name']);
dump($report->getSearchableColumns()); // Check labels

2. Alpine.js Console Errors

• Open browser console to check for Alpine.js errors during column search.

3. Common ReportBuilder Issues

Extension Points

1. Custom Column Search Logic

Override the default search behavior:

// resources/js/column-search.js
Alpine.data('columnSearch', () => ({
    searchColumns(columns, query) {
        // Custom search implementation
        return columns.filter(col =>
            col.label.toLowerCase().includes(query.toLowerCase()) ||
            col.key.toLowerCase().includes(query.toLowerCase())
        );
    }
}));

2. ReportBuilder Events

Listen for column search events (if supported):

// config/query-builder.php
'report_builder' => [
    'events' => [
        'search' => \App\Listeners\LogColumnSearch::class,
    ],
],

3. Custom ReportBuilder Drivers

ReportBuilder::driver('custom', function () {
    return new CustomReportBuilder();
});

4. Blade Component Customization

Extend the default ReportBuilder component:

<x-query-builder::report-builder :report="$report">
    @slot('extra')
        <button wire:click="refresh">Refresh</button>
    @endslot
</x-query-builder::report-builder>

5. Server-Side Column Filtering

For large datasets, combine client-side search with server-side filtering:

$report = new ReportBuilder(User::class);
$report->columns(['name' => 'Full Name']);

$query = $report->query()
    ->where('name', 'like', '%'.request('search').'%');

// Sync server-side search with client-side
document.getElementById('column-search').addEventListener('input', (e) => {
    window.location.search = `?search=${e.target.value}`;
});