Download the PHP package mohammad-fouladgar/eloquent-builder without Composer

Provides a Eloquent query builder for Laravel

This package allows you to build eloquent queries, based on incoming request parameters. It greatly reduces the complexity of the queries and conditions, which will make your code clean and maintainable.

Version Compatibility

Basic Usage

Suppose you want to get the list of the users with the requested parameters as follows:

In a common implementation, following code will be expected:

But after using the EloquentBuilder, the above code will turns into this:

You just need to define a filter for each parameter that you want to add to the query.

Installation

You can install the package via composer:

Warning: The Lumen framework is no longer supported!

Filters Namespace

The default namespace for all filters is App\EloquentFilters with the base name of the Model. For example, the filters' namespace will be App\EloquentFilters\User for the User model:

Customize via Config file

You can optionally publish the config file with:

And set the namespace for your model filters which will reside in:

Defining a Filter

Writing a filter is simple. Define a class that extends the Fouladgar\EloquentBuilder\Support\Foundation\Contracts\Filter abstract class. This class requires you to implement one method: apply. The apply method may add where constraints to the query as needed. Each filter class should be suffixed with the word Filter.

For example, take a look at the filter defined below:

Tip: Also, you can easily use local scopes in your filter. Because, they are instancing of the query builder.

Define filter[s] by artisan command

If you want to create a filter easily, you can use eloquent-builder:make artisan command. This command will accept at least two arguments which are Model and Filter:

There is also a possibility of creating multiple filters at the same time. To achieve this goal, you should pass multiple names to Filter argument:

Use a filter

You can use filters in multiple approaches:

Tip: It's recommended to put your query params inside a filter key as below:

And then use them this way: request()->filter.

Use Predefined Filters

This package provides several predefined filters using string conventions, so you can use them in your filter classes easily.

Tip: All value(s) in string conventions will be validated according to the used filter.

Date filters

Date filtering is one of the most commonly used filters that you may use in your filters by following these conventions: between:date1,date2,before:date, before_or_equal:date, after:date, after_or_equal:date , same:date, and equals:date.

Examples:

All you need is to define a filter and use the Fouladgar\EloquentBuilder\Concerns\FiltersDatesTrait trait. For example:

Number filters

Another predefined filters is Number filters that you can use in your filters. For example, it would be useful for price filter,score filters, and any numeric filters. You can follow these numeric conventions:
between:number1,number2,gt:number,gte:number,lt:number,lte:number, and equals:number.

Examples:

For example, make a ScoreFilter and use Fouladgar\EloquentBuilder\Concerns\FiltersNumbersTrait trait as below:

Sort filters

You may want to sort your query filter. There are some usage to make it:

Examples:

For example make a SortByFilter and use the Fouladgar\EloquentBuilder\Concerns\SortableTrait trait.

Tip: The sortable column(s) should be specified by $sortable attribute.

Authorizing Filter

The filter class also contains an authorize method. Within this method, you may check if the authenticated user actually has the authority to apply a given filter. For example, you may determine if a user has a premium account, can apply the StatusFilter to get listing the online or offline people:

By default, you do not need to implement the authorize method and the filter applies to your query builder. If the authorize method returns false, a HTTP response with a 403 status code will automatically be returned.

Ignore Filters on null value

Filter parameters are ignored if contain empty or null values.

Suppose you have a request something like this:

Only the "published_post" filter will be applied on your query.

Customize per domain/module

When you have a laravel project with custom directory structure, you might need to have multiple filters in multiple directories. For this purpose, you can use setFilterNamespace() method and pass the desired namespace to it.

For example, let's assume you have a project which implement a domain based structure:

In the above example, each domain has its own filters directory. So we can set and use filters custom namespace as following:

Note: When using setFilterNamespace(), default namespace and config file will be ignored.

Use as Dependency Injection

You may need to use the EloquentBuilder as DependencyInjection in a construct or a function method.

Suppose you have an UserController and you want get a list of the users with applying some filters on them:

That's it.

Testing

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

License

Eloquent-Builder is released under the MIT License. See the bundled LICENSE file for details.

Built with :heart: for you.