spatie/laravel-query-builder

Easily build Eloquent queries from API requests

Build Eloquent queries from API requests

[](https://packagist.org/packages/spatie/laravel-query-builder)   [](https://packagist.org/packages/spatie/laravel-query-builder)

Basic usage

Filter a query based on a request: /users?filter[name]=John:

use Spatie\QueryBuilder\QueryBuilder;

$users = QueryBuilder::for(User::class)
    ->allowedFilters('name')
    ->get();

// all `User`s that contain the string "John" in their name

Read more about filtering features like: partial filters, exact filters, scope filters, custom filters, ignored values, default filter values, ..., _(*1)

Including relations based on a request: /users?include=posts:

$users = QueryBuilder::for(User::class)
    ->allowedIncludes('posts')
    ->get();

// all `User`s with their `posts` loaded

Read more about include features like: including nested relationships, including relationship count, custom includes, ..., _(*2)

Sorting a query based on a request: /users?sort=id:

$users = QueryBuilder::for(User::class)
    ->allowedSorts('id')
    ->get();

// all `User`s sorted by ascending id

Read more about sorting features like: custom sorts, sort direction, ..., _(*3)

Works together nicely with existing queries:

$query = User::where('active', true);

$userQuery = QueryBuilder::for($query) // start from an existing Builder instance
    ->withTrashed() // use your existing scopes
    ->allowedIncludes('posts', 'permissions')
    ->where('score', '>', 42); // chain on any of Laravel's query builder methods

Selecting fields for a query: /users?fields[users]=id,email

$users = QueryBuilder::for(User::class)
    ->allowedFields(['id', 'email'])
    ->get();

// the fetched `User`s will only have their id & email set

Read more about selecting fields., _(*4)

Support us

, _(*5)

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products., _(*6)

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall., _(*7)

Installation

You can install the package via composer:, _(*8)

composer require spatie/laravel-query-builder

Read the installation notes on the docs site: https://spatie.be/docs/laravel-query-builder/v5/installation-setup., _(*9)

Documentation

You can find the documentation on https://spatie.be/docs/laravel-query-builder/v5., _(*10)

Find yourself stuck using the package? Found a bug? Do you have general questions or suggestions for improving the media library? Feel free to create an issue on GitHub, we'll try to address it as soon as possible., _(*11)

If you've found a bug regarding security please mail security@spatie.be instead of using the issue tracker., _(*12)

Upgrading

Please see UPGRADING.md for details., _(*13)

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently., _(*14)

Contributing

Please see CONTRIBUTING for details., _(*15)

Security

If you've found a bug regarding security please mail security@spatie.be instead of using the issue tracker., _(*16)

Credits

• Alex Vanderbist
• All Contributors

License

The MIT License (MIT). Please see License File for more information., _(*17)