Download the PHP package albetnov/laravel-filterable without Composer

Query String based filter for Laravel

A Laravel Model Filterable to automatically filter a model based on given query string

Installation

You can install the package via composer:

Usage

Simply add Filterable trait in your model and define either $filterableColumns or filterableColumns() (if you need extra logic) to define a filterable columns:

Getting Filterable Columns

If both are defined, Filterable will priority the method over property. As defined in: Filterable.php

If none exist though, Filterable will throws PropertyNotExist exception.

Filterable Type

There are Five FilterableType options available:

• Number
  This type will cast the given payload to either float or int, depending on whether the string contains a . prefix (indicating a float) or not (indicating an int).

• Text
  A type designed for handling text-based filters.

• Date
  A type intended for handling date-based filters. This will cast the payload to the Carbon format and adjust the query accordingly.

• Boolean
  A type intended for handling boolean-based filters. This type will cast the payload to boolean depending on 0 and 1.

Modifiers

Each of the FilterableType supports a modifier to alter the behaviour of filtering from the assigned field. There are 2 modifiers you can use for now.

• limit
  Allows you to limit the available operator, leaving the rest of the operators become invalid and throws OperatorNotExist exception. The function have one argument receiving an array of Operators. Usage Example:

• related
  Allows you to replace the query to use whereHas so that the filter apply to relation level. The function receives 2 arguments, first is the relationship name, and second is the extra query condition which are optional. Usage Example:

The modifiers can be chained together: FilterableType::DATE->related()->limit() to combine conditions

Custom Type

Custom Type does not support modifier.

As mentioned before there are 5 types exist for Filterable, the last one is custom which are treated differently. Custom Type is part of static method of FilterableType and therefore requires you to define it in filterableColumns() method.

The custom method accept one argument, $allowedOperators that are an array of Operators. This argument used to define the whitelist of allowed operators for your custom filter.

The custom type requires a handler, both of the handler and the field have to be defined under this convention:

Notice that the columns are defined in snake case while the method is camel case. Your function should also have three arguments defined. First is the Builder, a raw operator, and finally a raw value. The raw term means that these value are not formatted and they are passed quickly from the query string. However, they are validated.

Using in model

Just call filter scope and you're set:

Request Schema

Here is the expected request payload schema that can be read by Laravel Filterable:

All the filters must be placed within filters key and the values should be an array of object containing:

• fields (String)
  Determine which field should be filtered
• operator (String)
  What kind of the operator to be used in the filter context
• value (String)
  The expected value

The above schema when mapped to query string will be like this:
?filters[0][field]=customer_name&filters[0][operator]=eq&filters[0][value]=asep

Supported Operators

• eq: Checks if the value is equal to the specified input.
• neq: Checks if the value is not equal to the specified input.
• contains: Checks if the value contains the specified input.
• starts_with: Checks if the value starts with the specified input.
• ends_with: Checks if the value ends with the specified input.
• not_contains: Checks if the value does not contain the specified input.
• in (array): Checks if the value is one of the specified inputs.
• not_in (array): Checks if the value is not any of the specified inputs.
• have_all (array): Checks if the value has all the specified inputs.
• gt: Checks if the value is greater than the specified input.
• lt: Checks if the value is less than the specified input.
• gte: Checks if the value is greater than or equal to the specified input.
• lte: Checks if the value is less than or equal to the specified input.

Limitations

The value is limited exclusively to the string type, and each casting is performed through types defined in filterableColumns. Ambiguous casting may occur forarrays with items containing , as the value delimiter. Please avoid using , in your values, as they are used as the internal array delimiter. Another case could involve numbers with more than one . delimiter.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• albetnov

License

The MIT License (MIT). Please see License File for more information.