PHP Laravel eloquent query-builder
Need help with eloquent-builder?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.
mohammad-fouladgar

Description

Provides an Eloquent Query Builder for Laravel or Lumen.

232 Stars 34 Forks MIT License 240 Commits 1 Opened issues

Services available

Need anything else?

Provides a Eloquent query builder for Laravel or Lumen

alt text

Build Status Coverage Status Quality Score StyleCI Latest Stable Version Total Downloads License

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:

php
//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: ```php <?php

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-&gt;has('gender')) {
    $users-&gt;where('gender', $request-&gt;gender);
}

// A User model may have an infinite numbers of Post(One-To-Many).
if ($request-&gt;has('has_published_post')) {
    $users-&gt;where(function ($query) use ($request) {
        $query-&gt;whereHas('posts', function ($query) use ($request) {
            $query-&gt;where('is_published', $request-&gt;has_published_post);
        });
    });
}

return $users-&gt;get();

}

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

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-&gt;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.

Laravel <= 5.4.x

If you don't use Auto-Discovery, add the ServiceProvider to the providers array in

config/app.php
file ```php 'providers' => [ /* * Package Service Providers... */ Fouladgar\EloquentBuilder\ServiceProvider::class, ],
And add the **facade** to your ``config/app.php`` file
```php
/*
|--------------------------------------------------------------------------
| Class Aliases
|--------------------------------------------------------------------------
*/
'aliases' => [
    'EloquentBuilder' => Fouladgar\EloquentBuilder\Facade::class,
]

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
php
$app->withFacades();

Publish the configuration file

shell
php artisan eloquent-builder:publish
and add the configuration to the
bootstrap/app.php
file
php
$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:

sh
php artisan vendor:publish --provider="Fouladgar\EloquentBuilder\ServiceProvider" --tag="config"
And set the namespace for your model filters which will reside in:
php
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:

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: ```php <?php

// 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

Suppose you want use the

EloquentBuilder
as
DependencyInjection
in a
Repository
.

Let's have an example.We have a sample

UserRepository
as follows: ```php <?php

namespace App\Repositories;

use App\User; use Fouladgar\EloquentBuilder\EloquentBuilder;

class UserRepository implements UserRepositoryInterface {

public function __construct(EloquentBuilder $eloquentBuilder,User $user)
{
    $this->eloquentBuilder = $eloquentBuilder;
    $this->model = $user;
}

/**

  • On method call
  • / public function __call($method, $arguments) { return $this->model->$method(...$arguments); }

// other methods ...

public function filters(array $filters) { $this->model = $this->eloquentBuilder->to($this->model, $filters);

return $this;

}

}

The ``filters`` method applies the requested filters to the query by using ``EloquentBuilder`` injected.

Injecting The Repository

Now,we can simply "type-hint" it in the constructor of our UserController:

```php <?php namespace App\Http\Controllers;

use App\Repositories\UserRepository; use Illuminate\Http\Request;

class UserController extends Controller {

protected $users;

public function __construct(UserRepository $users)
{
    $this->users = $users;
}

public function index(Request $request)
{
    return $this-&gt;users-&gt;filters($request-&gt;filters)-&gt;get();
}

}

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 :heart: for you.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.