Provides a Eloquent query builder for Laravel or Lumen
This package allows you to build eloquent queries, based on request parameters. It greatly reduces the complexity of the queries and conditions, which will make your code clean and maintainable.
Basic Usage
Suppose you want to get the list of the users with the requested parameters as follows:
//Get api/user/search?age_more_than=25&gender=male&has_published_post=true
[
'age_more_than' => '25',
'gender' => 'male',
'has_published_post' => 'true',
]
In a common implementation, following code will be expected:
namespace App\Http\Controllers;
use App\User;
use Illuminate\Http\Request;
class UserController extends Controller
{
public function index(Request $request)
{
$users = User::where('is_active', true);
if ($request->has('age_more_than')) {
$users->where('age', '>', $request->age_more_than);
}
if ($request->has('gender')) {
$users->where('gender', $request->gender);
}
// A User model may have an infinite numbers of Post(One-To-Many).
if ($request->has('has_published_post')) {
$users->where(function ($query) use ($request) {
$query->whereHas('posts', function ($query) use ($request) {
$query->where('is_published', $request->has_published_post);
});
});
}
return $users->get();
}
}
But after using the EloquentBuilder, the above code will turns into this:
namespace App\Http\Controllers;
use App\User;
use EloquentBuilder;
use Illuminate\Http\Request;
class UserController extends Controller
{
public function index(Request $request)
{
$users = EloquentBuilder::to(User::class, $request->all());
return $users->get();
}
}
You just need to define a filter for each parameter that you want to add to the query.
Installation
Laravel
You can install the package via composer:
composer require mohammad-fouladgar/eloquent-builder
Laravel 5.5 uses Package Auto-Discovery, so you are not required to add ServiceProvider manually.
Lumen
You can install the package via composer:
composer require mohammad-fouladgar/eloquent-builder
For Lumen, add the LumenServiceProvider to the bootstrap/app.php file
/*
|--------------------------------------------------------------------------
| Register Service Providers...
|--------------------------------------------------------------------------
*/
$app->register(\Fouladgar\EloquentBuilder\LumenServiceProvider::class);
For using the facade you have to uncomment the line $app->withFacades(); in the bootstrap/app.php file
After uncommenting this line you have the EloquentBuilder facade enabled
$app->withFacades();
Publish the configuration file
php artisan eloquent-builder:publish
and add the configuration to the bootstrap/app.php file
$app->configure('eloquent-builder');
...
$app->register(\Fouladgar\EloquentBuilder\LumenServiceProvider::class);
Important : this needs to be before the registration of the service provider.
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:
├── app
├── Console
│ └── Kernel.php
├── EloquentFilters
│ └── User
│ ├── AgeMoreThanFilter.php
│ └── GenderFilter.php
└── Exceptions
└── Handler.php
Customize via Config file
You can optionally publish the config file with:
php artisan vendor:publish --provider="Fouladgar\EloquentBuilder\ServiceProvider" --tag="config"
And set the namespace for your model filters which will reside in:
return [
/*
|--------------------------------------------------------------------------
| Eloquent Filter Settings
|--------------------------------------------------------------------------
|
| This is the namespace all you Eloquent Model Filters will reside
|
*/
'namespace' => 'App\\EloquentFilters\\',
];
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:
.
├── app
├── bootstrap
├── config
├── database
├── Domains
│ ├── Store
│ │ ├── database
│ │ │ └── migrations
│ │ ├── src
│ │ ├── Filters // we put our Store domain filters here!
│ │ │ └── StoreFilter.php
│ │ ├── Entities
│ │ ├── Http
│ │ └── Controllers
│ │ ├── routes
│ │ └── Services
│ ├── User
│ │ ├── database
│ │ │ └── migrations
│ │ ├── src
│ │ ├── Filters // we put our User domain filters here!
│ │ │ └── UserFilter.php
│ │ ├── Entities
│ │ ├── Http
│ │ └── Controllers
│ │ ├── routes
│ │ └── Services
...
In the above example, each domain has its own filters directory. So we can set and use filters custom namespace as following:
$stores = EloquentBuilder::setFilterNamespace('Domains\\Store\\Filters')
->to(\Domains\Entities\Store::class, $filters)->get();
Note: When using
setFilterNamespace(), default namespace and config file will be ignored.
Define 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:
namespace App\EloquentFilters\User;
use Fouladgar\EloquentBuilder\Support\Foundation\Contracts\Filter;
use Illuminate\Database\Eloquent\Builder;
class AgeMoreThanFilter extends Filter
{
/**
* Apply the age condition to the query.
*
* @param Builder $builder
* @param mixed $value
*
* @return Builder
*/
public function apply(Builder $builder, $value): Builder
{
return $builder->where('age', '>', $value);
}
}
Tip: Also, you can easily use local scopes in your filter. Because they are instance 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:
php artisan eloquent-builder:make user age_more_than
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:
php artisan eloquent-builder:make user age_more_than gender
Use a filter
You can use filters in multiple approaches:
// Use by a model class name
$users = EloquentBuilder::to(\App\User::class, request()->all())->get();
// Use by existing query
$query = \App\User::where('is_active', true);
$users = EloquentBuilder::to($query, request()->all())->where('city', 'london')->get();
// Use by instance of a model
$users = EloquentBuilder::to(new \App\User(), request()->filter)->get();
Tip: It's recommended to put your query params inside a filter key as below:
user/search?filter[age_more_than]=25&filter[gender]=male
And then use them this way: request()->filter.
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:
/**
* Determine if the user is authorized to make this filter.
*
* @return bool
*/
public function authorize(): bool
{
if(auth()->user()->hasPremiumAccount()){
return true;
}
return false;
}
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:
//Get api/user/search?filter[name]&filter[gender]=null&filter[age_more_than]=''&filter[published_post]=true
EloquentBuilder::to(User::class, $request->filter);
// filters result will be:
$filters = [
'published_post' => true
];
Only the "published_post" filter will be applied on your query.
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:
namespace App\Controllers;
use App\Models\User;
use App\Http\Resources\UserResource;
use Fouladgar\EloquentBuilder\EloquentBuilder as Builder;
use Fouladgar\EloquentBuilder\Exceptions\NotFoundFilterException;
use Illuminate\Http\Request;
class UserController
{
public function index(Request $request, User $user, Builder $builder)
{
$users = $user->newQuery()->where('is_active', true);
try {
$builder->to($users, $request->filter);
} catch (NotFoundFilterException $filterException) {
//...
}
return UserResource::collection($users->get());
}
}
That's it.
Testing
composer test
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
146 Jan 2, 2023
75 Dec 7, 2022
149 Nov 11, 2022
35 Dec 15, 2022
5 Nov 2, 2022
3 Jan 1, 2022
36 Dec 17, 2022
2 Oct 14, 2021
307 Sep 23, 2022
15 Nov 20, 2022
1.7k Dec 31, 2022
340 Dec 31, 2022
4 Oct 2, 2022
24 Nov 29, 2022
1.3k Dec 22, 2022
1 Jan 16, 2022
306 Nov 28, 2022
997 Dec 22, 2022
2 Oct 16, 2022