Introduction | laravel-query-builder | Spatie SPATIE Laravel Query Builder ======================== spatie.be/open-source [Docs](https://spatie.be/docs) [Laravel-query-builder](https://spatie.be/docs/laravel-query-builder/v3) Introduction Version v7 v6 v5 v4 v3 v2 Other versions for crawler [v7](https://spatie.be/docs/laravel-query-builder/v7) [v6](https://spatie.be/docs/laravel-query-builder/v6) [v5](https://spatie.be/docs/laravel-query-builder/v5) [v4](https://spatie.be/docs/laravel-query-builder/v4) [v3](https://spatie.be/docs/laravel-query-builder/v3) [v2](https://spatie.be/docs/laravel-query-builder/v2) - [ Introduction ](https://spatie.be/docs/laravel-query-builder/v3/introduction) - [ Requirements ](https://spatie.be/docs/laravel-query-builder/v3/requirements) - [ About us ](https://spatie.be/docs/laravel-query-builder/v3/about-us) - [ Installation & setup ](https://spatie.be/docs/laravel-query-builder/v3/installation-setup) - [ Support us ](https://spatie.be/docs/laravel-query-builder/v3/support-us) - [ Questions and issues ](https://spatie.be/docs/laravel-query-builder/v3/questions-issues) - [ Changelog ](https://spatie.be/docs/laravel-query-builder/v3/changelog) Features -------- - [ Filtering ](https://spatie.be/docs/laravel-query-builder/v3/features/filtering) - [ Sorting ](https://spatie.be/docs/laravel-query-builder/v3/features/sorting) - [ Including relationships ](https://spatie.be/docs/laravel-query-builder/v3/features/including-relationships) - [ Selecting fields ](https://spatie.be/docs/laravel-query-builder/v3/features/selecting-fields) - [ Appending attributes ](https://spatie.be/docs/laravel-query-builder/v3/features/appending-attributes) Advanced usage -------------- - [ Extending query builder ](https://spatie.be/docs/laravel-query-builder/v3/advanced-usage/extending-query-builder) - [ Pagination ](https://spatie.be/docs/laravel-query-builder/v3/advanced-usage/pagination) - [ Front-end implementation ](https://spatie.be/docs/laravel-query-builder/v3/advanced-usage/front-end-implementation) - [ Multi value delimiter ](https://spatie.be/docs/laravel-query-builder/v3/advanced-usage/multi-value-delimiter) You are viewing the documentation for **an older version** of this package. You can check the version you are using with the following command: ` composer show spatie/laravel-query-builder ` Laravel Query Builder ======================= Build Eloquent queries from API requests ---------------------------------------- [ Repository ](https://github.com/spatie/laravel-query-builder) 27,172,319 4,406 Introduction ------------ ### On this page 1. [ Basic usage ](#content-basic-usage) 2. [ We have badges! ](#content-we-have-badges) This package allows you to filter, sort and include eloquent relations based on a request. The `QueryBuilder` used in this package extends Laravel's default Eloquent builder. This means all your favorite methods and macros are still available. Query parameter names follow the [JSON API specification](http://jsonapi.org/) as closely as possible. Here's how we use the package ourselves in [Mailcoach](https://mailcoach.app). 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, ...](https://docs.spatie.be/laravel-query-builder/v2/features/filtering/) ### 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, ...](https://docs.spatie.be/laravel-query-builder/v2/features/including-relationships/) ### 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, ...](https://docs.spatie.be/laravel-query-builder/v2/features/sorting/) ### 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=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.](https://docs.spatie.be/laravel-query-builder/v2/features/selecting-fields/) ### Appending attributes to a query: `/users?append=full_name` ``` $users = QueryBuilder::for(User::class) ->allowedAppends('full_name') ->get() ->toJson(); // the resulting JSON will have the `getFullNameAttribute` attributes included ``` [Read more about appending attributes.](https://docs.spatie.be/laravel-query-builder/v2/features/appending-attributes/) We have badges! --------------------------------------------------------------------------------------------------- [![Latest Version on Packagist](https://img.shields.io/packagist/v/spatie/laravel-query-builder.svg?style=flat-square)](https://packagist.org/packages/spatie/laravel-query-builder)[![Build Status](https://img.shields.io/circleci/project/github/spatie/laravel-query-builder/master.svg?style=flat-square)](https://circleci.com/gh/spatie/laravel-query-builder)[![StyleCI](https://styleci.io/repos/117567334/shield?branch=master)](https://styleci.io/repos/117567334)[![Quality Score](https://img.shields.io/scrutinizer/g/spatie/laravel-query-builder.svg?style=flat-square)](https://scrutinizer-ci.com/g/spatie/laravel-query-builder)[![Total Downloads](https://img.shields.io/packagist/dt/spatie/laravel-query-builder.svg?style=flat-square)](https://packagist.org/packages/spatie/laravel-query-builder) ![Look at all those badges](https://i.imgflip.com/36x6d6.jpg)