Eloquent Filtering Laravel Package

title: 'Custom Filters' version: 'v2' icon: 'code' iconType: 'solid'

Overview

This package provides the ability for you to create two different types of custom filters. - Field Filter. - Custom Filter.

'custom_filters' => [
    YourCustomFilter::class,
],

Field Filter

php artisan make:eloquent-filter LowerCaseFilter --type=field

Class

class LowerCaseFilter implements FilterMethod, Targetable
{
    use FieldFilter;

    public function __construct(
        protected string $value,
    ) {
    }

    /*
     * The unique identifier of the filter.
     */
    public static function type(): string
    {
        return '$lowercase';
    }

    /*
     * The format that the filter data must adhere to.
     * Defined as laravel validator rules.
     * On fail: throws MalformedFilterFormatException.
     */
    public static function format(): array
    {
        return [
            'value' => ['required', 'string'],
        ];
    }

    /*
     * Apply the filter logic.
     */
    public function apply(Builder $query): Builder
    {
        $target = $this->eloquentContext->qualifyColumn($this->target);

        return $query->where(
            DB::raw("LOWER({$target})"),
            strtolower($this->value)
        );
    }
}

Usage

public function allowedFilters(): AllowedFilterList
{
    return Filter::only(
        Filter::field('name', ['$lowercase']),
    );
}

Custom Filter

php artisan make:eloquent-filter AdminFilter --type=custom

Class

class AdminFilter implements FilterMethod
{
    use CustomFilter;

    /*
     * The unique identifier of the filter.
     */
    public static function type(): string
    {
        return '$admin';
    }

    /*
     * Apply the filter logic.
     */
    public function apply(Builder $query): Builder
    {
        return $query->where(
            $this->eloquentContext()->qualifyColumn('admin'),
            true
        );
    }
}

Usage

public function allowedFilters(): AllowedFilterList
{
    return Filter::only(
        Filter::custom('$admin'),
    );
}

Custom Filter Notes

Format/Validation

To specify validation messages and attributes along with the rules, you may return a IndexZer0\EloquentFiltering\Filter\Validation\ValidatorProvider from the ::format() method.

public static function format(): ValidatorProvider
{
    return ValidatorProvider::from([
        'value' => ['required', 'string'],
    ], [
        'string' => 'The :attribute must be a string.',
    ], [
        'value' => 'value attribute',
    ]);
}

Modifiers

Adding modifiers to your custom filters is achieved by:

• Implement interface:
  • IndexZer0\EloquentFiltering\Filter\Contracts\FilterMethod\Modifiable
• Use trait:
  • IndexZer0\EloquentFiltering\Filter\Traits\FilterMethod\Composables\HasModifiers
• Define supportedModifiers() method on the filter class.
• Using $this->hasModifier('modifier_name') in the apply() implementation.

class YourFilterWithModifiers implements
    FilterMethod,
    Targetable,
    Modifiable
{
    use FieldFilter;
    use HasModifiers;

    //...

    public static function supportedModifiers(): array
    {
        return ['special'];
    }

    public function apply(Builder $query): Builder
    {
        if ($this->hasModifier('special')) {
            // Perform your special logic.
        } else {
            // Perform your regular logic.
        }
    }

    //...
}

Qualifying Columns

All FilterMethod classes have access to an EloquentContext object that allows you to qualifyColumn of the target.

• Use this method to ensure your query is prefixing the column name with the database table.

Benefits of using this method:

• Prevents ambiguous columns in queries where you're also joining to another table with the same column.
• Handles using the correct table name for ->pivot() allowed field filters.

public function apply(Builder $query): Builder
{
    return $query->where(
        $this->eloquentContext()->qualifyColumn($this->target),
        true
    );
}