Laravel Purity

Laravel Purity is a package designed to simplify complex data filtering and sorting logic for Eloquent queries in Laravel. It allows frontend users to apply filters and sorting via URL query string parameters. The package's filtering and sorting syntax is inspired by Strapi's API functionality.

// Basic usage pattern
$posts = Post::filter()->get();

Laravel Purity is a package designed to simplify and enhance query construction in Laravel applications. Key features include:

• Simplicity: Focused on ease of use.
• Rename and Restrict: Allows for elegant customization and control over which fields are queryable.
• Predefined Methods: Provides over 20 filtering methods to refine queries.
• Relation Friendly: Supports filtering and sorting through columns in related models.
• Livewire Support: Integrates directly with Laravel Livewire.
• Multi-column Friendly: Enables filtering and sorting data across multiple columns easily.

Laravel Purity provides several advanced capabilities for managing Eloquent queries:

• Livewire support: Seamless integration with Livewire components.
• Field Management: Ability to rename and restrict which fields can be filtered.
• Advanced Filtering: Various filter methods and the ability to filter by columns in related models.
• Customization: Support for creating custom filters.
• Sorting: Multi-column sorting capabilities.
• Frontend Friendly: Works well with the JavaScript qs package for constructing query strings.

Laravel Purity allows you to simplify complex Eloquent filtering and sorting logic by enabling query string parameters to drive your database queries.

To use it, you call the filter() method on an Eloquent model or query builder. Once filter() is added, the package automatically maps URL query string parameters to your model's filtering logic. For example, a request like ?filters[column_name][operator]=value will be processed by the package to apply that filter to the query.

// 1. Add filter() to your Eloquent query
$posts = Post::filter()->get();

// 2. The query is now automatically filtered by URL parameters,
// e.g., GET /api/posts?filters[title][$contains]=Purity

By default, Purity automatically retrieves filter parameters from the find index within the query parameters (e.g., GET /api/users?find[name][$eq]=John).

You can override this default behavior by passing an explicit array of parameters directly into the filter() or sort() methods. This is useful when your parameters are located under a different key or are provided manually from a different source.

// Default behavior: gets filters from 'find' query params
// GET /api/users?find[name][$eq]=John
Post::filter(request()->query('find'))->get();

// Overriding default: passing custom params directly
Post::filter(['title' => ['$eq' => 'good post']])->get();

// Overriding sort: passing custom sort array
Post::sort(['title', 'id:desc'])->get();

To enable sorting capabilities on an Eloquent model, add the Abbasudo\Purity\Traits\Sortable trait to your model class. Once the trait is added, you can call the sort() method on your model's query builder in your controllers to apply sorting parameters from the request.

use Abbasudo\\Purity\Traits\Sortable;

class Post extends Model
{
    use Sortable;
    
    //
}

// In your controller:
return Post::sort()->get();

To enable filtering capabilities on an Eloquent model, add the Abbasudo\Purity\Traits\Filterable trait to your model class. Once the trait is added, you can call the filter() method on your model's query builder in your controllers to apply requested filters from the request. By default, filter() allows access to all available filters defined for that model.

use Abbasudo\Purity\Traits\Filterable;

class Post extends Model
{
    use Filterable;
    
    //
}

// In your controller:
return Post::filter()->get();

To allow clients to sort by names other than the actual database column names, you can provide a mapping within the $sortFields property on your Model.

If you define 'mobile' => 'phone' in $sortFields, the client can send ?sort=phone to sort the results by the mobile database column. You can also include simple strings for fields that do not require renaming.

// App\Models\User

// The actual database column is 'mobile', but the client should use 'phone' for sorting.
protected $sortFields = [
  'name',
  'mobile' => 'phone',
];

Complex filtering allows you to combine multiple conditions using logical operators like $or and $and. This is useful for requesting data that meets specific, non-linear criteria.

To use $or, pass an array of objects to the $or key within the filters object. Each object in the array represents a set of conditions where if any one of them is met, the record is included.

const qs = require('qs');
const query = qs.stringify({
  filters: {
    $or: [
      { date: { $eq: '2020-01-01' } },
      { date: { $eq: '2020-01-02' } },
    ],
    author: { name: { $eq: 'Kai doe' } },
  },
}, { encodeValuesOnly: true });

await request(`/api/books?${query}`);

You can create a new custom filter class using the Artisan command. This will generate a new class file in your designated filters directory.

To generate a filter named EqualFilter, run:

php artisan make:filter EqualFilter

In Version 2, the arguments for the filter function were changed. The filter function no longer accepts filter methods directly. Instead, the filter function now accepts a filter source.

If you need to specify allowed filter methods, you must now use filterBy as described in the Restrict Filters documentation.