Filters Overview

Introduction

The Filters system provides a powerful, pipeline-based approach to filtering Eloquent queries in the Gestión de Ventas Laravel ERP. It implements a modular architecture where individual filter classes can be composed together to create complex filtering logic.

Architecture

The filter system is built on three core components:

FilterInterface

Contract that all filters must implement

QueryFilter

Base class that orchestrates filter application

Individual Filters

Specific filter implementations for each criteria

FilterInterface

The base contract that all filters implement:

app/Filters/Contracts/FilterInterface.php

<?php

namespace App\Filters\Contracts;

use Illuminate\Database\Eloquent\Builder;

interface FilterInterface
{
    public function apply(Builder $query): Builder;
}

Every filter must implement the apply() method, which receives an Eloquent query builder and returns the modified builder.

QueryFilter Base Class

The abstract base class that coordinates filter application:

app/Filters/Base/QueryFilter.php

<?php

namespace App\Filters\Base;

use Illuminate\Http\Request;
use Illuminate\Database\Eloquent\Builder;
use App\Filters\Contracts\FilterInterface;

abstract class QueryFilter implements FilterInterface
{
    protected Request $request;
    protected Builder $query;

    public function __construct(Request $request)
    {
        $this->request = $request;
    }

    public function apply(Builder $query): Builder
    {
        $this->query = $query;

        foreach ($this->filters() as $key => $filterClass) {
            if ($this->request->filled($key)) {
                (new $filterClass($this->request))->apply($this->query);
            }
        }

        return $this->query;
    }

    /**
     * Map request keys to Filter classes
     */
    abstract protected function filters(): array;
}

Key Features:

Iterates through defined filters
Only applies filters when the request parameter is present
Maintains the query builder reference throughout the pipeline
Child classes define the filter mapping via filters() method

How It Works

Define Filter Classes

Create a main filter class extending QueryFilter that maps request parameters to individual filter implementations.

class SaleFilters extends QueryFilter
{
    protected function filters(): array
    {
        return [
            'search'       => SaleSearchFilter::class,
            'client_id'    => SaleClientFilter::class,
            'from_date'    => SaleDateFilter::class,
            'status'       => SaleStatusFilter::class,
        ];
    }
}

Create Individual Filters

Each filter implements FilterInterface and contains specific filtering logic.

class SaleStatusFilter implements FilterInterface
{
    public function __construct(protected Request $request) {}

    public function apply(Builder $query): Builder
    {
        $value = $this->request->input('status');
        return $value ? $query->where('status', $value) : $query;
    }
}

Apply in Controllers

Instantiate the filter class with the request and apply it to your query.

public function index(Request $request)
{
    $sales = (new SaleFilters($request))
        ->apply(Sale::query()->with(['client', 'warehouse']))
        ->latest()
        ->paginate(15);

    return view('sales.index', compact('sales'));
}

Filter Types

The system includes several common filter patterns:

Search Filters

Perform LIKE queries across multiple fields:

app/Filters/Sales/SalesFilters/SaleSearchFilter.php

class SaleSearchFilter implements FilterInterface
{
    public function __construct(protected Request $request) {}

    public function apply(Builder $query): Builder
    {
        $value = $this->request->input('search');
        if (!$value) return $query;

        return $query->where(function($q) use ($value) {
            $q->where('number', 'like', "%{$value}%")
              ->orWhere('notes', 'like', "%{$value}%")
              ->orWhereHas('client', function($subQ) use ($value) {
                  $subQ->where('name', 'like', "%{$value}%");
              });
        });
    }
}

Date Range Filters

Filter records between two dates:

app/Filters/Sales/SalesFilters/SaleDateFilter.php

class SaleDateFilter implements FilterInterface
{
    public function __construct(protected Request $request) {}

    public function apply(Builder $query): Builder
    {
        $from = $this->request->input('from_date');
        $to = $this->request->input('to_date');

        return $query
            ->when($from, function($q) use ($from) {
                return $q->whereDate('sale_date', '>=', Carbon::parse($from));
            })
            ->when($to, function($q) use ($to) {
                return $q->whereDate('sale_date', '<=', Carbon::parse($to));
            });
    }
}

Amount Range Filters

Filter by minimum and maximum amounts:

app/Filters/Sales/SalesFilters/SaleAmountRangeFilter.php

class SaleAmountRangeFilter implements FilterInterface
{
    public function __construct(protected Request $request) {}

    public function apply(Builder $query): Builder
    {
        $min = $this->request->input('min_amount');
        $max = $this->request->input('max_amount');

        return $query
            ->when($min, fn($q) => $q->where('total_amount', '>=', $min))
            ->when($max, fn($q) => $q->where('total_amount', '<=', $max));
    }
}

Exact Match Filters

Filter by exact field values:

app/Filters/Sales/SalesFilters/SaleStatusFilter.php

class SaleStatusFilter implements FilterInterface
{
    public function __construct(protected Request $request) {}

    public function apply(Builder $query): Builder
    {
        $value = $this->request->input('status');
        return $value ? $query->where('status', $value) : $query;
    }
}

Boolean Logic Filters

Filter based on conditional logic:

app/Filters/Client/ClientHasDebtFilter.php

class ClientHasDebtFilter implements FilterInterface
{
    public function __construct(protected Request $request) {}

    public function apply(Builder $query): Builder
    {
        $value = $this->request->input('has_debt');
        
        if ($value === 'yes') {
            return $query->where('balance', '>', 0);
        }
        
        if ($value === 'no') {
            return $query->where('balance', '<=', 0);
        }
        
        return $query;
    }
}

Real-World Examples

Sales Filtering System

app/Filters/Sales/SalesFilters/SaleFilters.php

class SaleFilters extends QueryFilter
{
    protected function filters(): array
    {
        return [
            'search'       => SaleSearchFilter::class,
            'client_id'    => SaleClientFilter::class,
            'warehouse_id' => SaleWarehouseFilter::class,
            'payment_type' => SalePaymentTypeFilter::class,
            'tipo_pago_id' => SaleTipoPagoFilter::class,
            'status'       => SaleStatusFilter::class,
            'from_date'    => SaleDateFilter::class,
            'min_amount'   => SaleAmountRangeFilter::class,
        ];
    }
}

Payment Filtering System

app/Filters/Accounting/PaymentsFilters/PaymentFilters.php

class PaymentFilters extends QueryFilter
{
    protected function filters(): array
    {
        return [
            'search'       => PaymentSearchFilter::class,
            'client_id'    => PaymentClientFilter::class,
            'tipo_pago_id' => PaymentMethodFilter::class,
            'status'       => PaymentStatusFilter::class,
            'from_date'    => PaymentDateFilter::class,
            'min_amount'   => PaymentAmountRangeFilter::class,
        ];
    }
}

Client Filtering System

app/Filters/Client/ClientFilters.php

class ClientFilters extends QueryFilter
{
    protected function filters(): array
    {
        return [
            'search'         => ClientSearchFilter::class,
            'estado_cliente' => ClientBusinessStatusFilter::class,
            'state'          => ClientStateFilter::class,
            'type'           => ClientTypeFilter::class,
            'tax_type'       => ClientTaxIdentifierFilter::class,
            'from_date'      => ClientDateFilter::class,
            'has_debt'       => ClientHasDebtFilter::class,
            'over_limit'     => ClientOverLimitFilter::class,
        ];
    }
}

Controller Integration

Here’s a complete example from the Payment controller:

app/Http/Controllers/Accounting/PaymentController.php

public function index(Request $request)
{
    $visibleColumns = $request->input('columns', PaymentTable::defaultDesktop());
    $perPage = $request->input('per_page', 15);

    $payments = (new PaymentFilters($request))
        ->apply(Payment::query()->with(['client', 'receivable', 'tipoPago', 'creator']))
        ->latest()
        ->paginate($perPage)
        ->withQueryString();

    $catalogs = $this->catalogService->getForFilters();

    if ($request->ajax()) {
        return view('accounting.payments.partials.table', [
            'items'          => $payments,
            'visibleColumns' => $visibleColumns,
            'allColumns'     => PaymentTable::allColumns(),
        ])->render();
    }

    return view('accounting.payments.index', array_merge(
        [
            'items'          => $payments,
            'visibleColumns' => $visibleColumns,
            'allColumns'     => PaymentTable::allColumns(),
        ],
        $catalogs
    ));
}

Export with Filters

Filters can be reused for data exports:

app/Http/Controllers/Accounting/PaymentController.php

public function export(Request $request)
{
    try {
        // Apply the same filters as the main table
        $query = (new PaymentFilters($request))
            ->apply(Payment::query());

        $fileName = 'reporte-pagos-' . now()->format('d-m-Y-H-i') . '.xlsx';

        return Excel::download(new PaymentsExport($query), $fileName);
    } catch (\Exception $e) {
        return back()->with('error', "Error al generar el reporte: " . $e->getMessage());
    }
}

Benefits

Modularity

Each filter is a separate, testable class with a single responsibility

Reusability

Filters can be shared across different modules (e.g., date filters)

Maintainability

Easy to add, modify, or remove filters without affecting others

Type Safety

Clear contracts ensure consistent behavior across all filters

Available Filter Systems

The ERP includes pre-built filter systems for:

Sales: Sales orders, invoices, NCF logs
Accounting: Payments, receivables, journal entries, document types
Clients: Client management with business status, debt, and credit limits
Inventory: Stock levels, movements, warehouses
Products: Products with categories, units, and active status
Point of Sale: POS terminals with status and client filters
Equipment: Equipment tracking by type and location

Models

Services

Filters

Introduction

Architecture

FilterInterface

QueryFilter

Individual Filters

FilterInterface

QueryFilter Base Class

How It Works

Filter Types

Search Filters

Date Range Filters

Amount Range Filters

Exact Match Filters

Boolean Logic Filters

Real-World Examples

Sales Filtering System

Payment Filtering System

Client Filtering System

Controller Integration

Export with Filters

Benefits

Modularity

Reusability

Maintainability

Type Safety

Available Filter Systems

Next Steps

Creating Filters

Query Builder

Build docs developers (and LLMs) love

Models

Services

Filters

​Introduction

​Architecture

FilterInterface

QueryFilter

Individual Filters

​FilterInterface

​QueryFilter Base Class

​How It Works

​Filter Types

​Search Filters

​Date Range Filters

​Amount Range Filters

​Exact Match Filters

​Boolean Logic Filters

​Real-World Examples

​Sales Filtering System

​Payment Filtering System

​Client Filtering System

​Controller Integration

​Export with Filters

​Benefits

Modularity

Reusability

Maintainability

Type Safety

​Available Filter Systems

​Next Steps

Creating Filters

Query Builder

Build docs developers (and LLMs) love

Introduction

Architecture

FilterInterface

QueryFilter Base Class

How It Works

Filter Types

Search Filters

Date Range Filters

Amount Range Filters

Exact Match Filters

Boolean Logic Filters

Real-World Examples

Sales Filtering System

Payment Filtering System

Client Filtering System

Controller Integration

Export with Filters

Benefits

Available Filter Systems

Next Steps