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/v7)  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/v7/introduction)
- [ Requirements ](https://spatie.be/docs/laravel-query-builder/v7/requirements)
- [ About us ](https://spatie.be/docs/laravel-query-builder/v7/about-us)
- [ Installation &amp; setup ](https://spatie.be/docs/laravel-query-builder/v7/installation-setup)
- [ Support us ](https://spatie.be/docs/laravel-query-builder/v7/support-us)
- [ Questions and issues ](https://spatie.be/docs/laravel-query-builder/v7/questions-issues)
- [ Changelog ](https://spatie.be/docs/laravel-query-builder/v7/changelog)

Features
--------

- [ Filtering ](https://spatie.be/docs/laravel-query-builder/v7/features/filtering)
- [ Sorting ](https://spatie.be/docs/laravel-query-builder/v7/features/sorting)
- [ Including relationships ](https://spatie.be/docs/laravel-query-builder/v7/features/including-relationships)
- [ Selecting fields ](https://spatie.be/docs/laravel-query-builder/v7/features/selecting-fields)

Advanced usage
--------------

- [ Extending query builder ](https://spatie.be/docs/laravel-query-builder/v7/advanced-usage/extending-query-builder)
- [ Pagination ](https://spatie.be/docs/laravel-query-builder/v7/advanced-usage/pagination)
- [ Multi value delimiter ](https://spatie.be/docs/laravel-query-builder/v7/advanced-usage/multi-value-delimiter)
- [ Front-end implementation ](https://spatie.be/docs/laravel-query-builder/v7/advanced-usage/front-end-implementation)

 Laravel Query Builder
=======================

Build Eloquent queries from API requests
----------------------------------------

 [    Repository ](https://github.com/spatie/laravel-query-builder)

    26,412,765

    4,396

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://spatie.be/docs/laravel-query-builder/v7/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://spatie.be/docs/laravel-query-builder/v7/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://spatie.be/docs/laravel-query-builder/v7/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://spatie.be/docs/laravel-query-builder/v7/features/selecting-fields/)

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)![Test Status](https://img.shields.io/github/actions/workflow/status/spatie/laravel-query-builder/run-tests.yml?label=tests&branch=main)[![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)
