Scramble 0.11.0 is here! Laravel Data support, schema enforcement and more
Learn more

Laravel Query Builder

On this page
Scramble PRO
Comprehensive API documentation generation for Spatie’s Laravel Data and Laravel Query Builder.
Are you a visual learner?
Get most out of Scramble with in-depth screencasts.
Scramble PRO demo
Learn about Query Builder support
In around 2 minutes

Spatie’s Laravel Query Builder is a great package that allows you to filter, sort and include eloquent relations based on a request. And because query parameter names follow the JSON API specification as closely as possible, this package is really a good tool when building APIs.

Scramble has Laravel Query Builder support as a part of Scramble PRO package. You can get Scramble PRO here: https://scramble.dedoc.co/pro. After purchasing, you will receive the license key to your email.

Installation

Installation instructions for `dedoc/scramble-pro`

Usage

If you already configured routes for Scramble, after you install Scramble PRO – you should be all set up. Scramble will generate the query parameters for Laravel Query Builder.

Documenting filters

To define filters, you can use allowedFilters method on a query builder instance.

use Spatie\QueryBuilder\QueryBuilder;
use App\Models\Company;
class CompaniesController extends Controller
{
public function index()
{
$companies = QueryBuilder::for(Company::class)
->allowedFilters(['name', 'created_at'])
->get();
// ...
}
}
Resulting documentation
companies.index
get
https://companies.app/api/companies
Request
query Params
filter[name]
string
filter[created_at]
string

Adding description to the filter

Also, you can add more description to a filter by adding comments and PHPDoc annotations. @example annotation can be used to specify examples, @var to specify a type, and @format to specify a format.

$companies = QueryBuilder::for(Company::class)
->allowedFilters([
/**
* The name to filter a company by. Multiple values can be passed, separated via `,` (`Nike,Tesla`)
* @example Tesla
*/
'name',
/**
* The date of the creation of the company.
* @format date
*/
'created_at',
])
->get();
}
Resulting documentation
companies.index
get
https://companies.app/api/companies
Request
query Params
filter[name]
string
The name to filter a company by. Multiple values can be passed, separated via `,` (`Nike,Tesla`)
Example
Tesla
filter[created_at]
string<date>
The date of the creation of the company.

Documenting sorts

To define allowed sorts, you can use allowedSorts method on a query builder instance.

When Scramble documents allowed sorts, it will make examples from the allowed values.

use Spatie\QueryBuilder\QueryBuilder;
use App\Models\Company;
class CompaniesController extends Controller
{
public function index()
{
$companies = QueryBuilder::for(Company::class)
->allowedSorts(['name', 'created_at'])
->get();
// ...
}
}
Resulting documentation
companies.index
get
https://companies.app/api/companies
Request
query Params
sort
string
Available sorts are `name`, `created_at`. You can sort by multiple options by separating them with a comma. To sort in descending order, use `-` sign in front of the sort, for example: `-name`.

You can use defaultSorts (or defaultSort) method, to specify the default sort. Scramble will document it as well.

$companies = QueryBuilder::for(Company::class)
->allowedSorts(['name', 'created_at'])
->defaultSort('-name')
->get();
Resulting documentation
companies.index
get
https://companies.app/api/companies
Request
query Params
sort
string
Available sorts are `name`, `created_at`. You can sort by multiple options by separating them with a comma. To sort in descending order, use `-` sign in front of the sort, for example: `-name`.
Default
-name

Documenting includes

You can allow including relationships using allowedIncludes method on a query builder.

Scramble support both passing them as a string (including a relationship, count, existence), or passing allowed includes as instances of Spatie\QueryBuilder\AllowedInclude class.

$companies = QueryBuilder::for(Company::class)
->allowedIncludes([
'jobs',
AllowedInclude::count('employees_count'),
])
->get();
Resulting documentation
companies.index
get
https://companies.app/api/companies
Request
query Params
include
string
Available includes are `jobs`, `jobsCount`, `jobsExists`, `employees_count`. You can include multiple options by separating them with a comma.

Documenting fields

You can enable a selection of specific fields using allowedFields method.

You can allow selecting the fields of the model instance being queried, as well as selecting fields of the included relations. When describing allowed fields of the included relations, Scramble will separate it into a different query parameter.

$companies = QueryBuilder::for(Company::class)
->allowedFields(['id', 'name', 'jobs.id', 'jobs.title', 'created_at'])
->get();
Resulting documentation
companies.index
get
https://companies.app/api/companies
Request
query Params
fields
string
Available fields are `id`, `name`, `created_at`. You can include multiple options by separating them with a comma.
fields[jobs]
string
Available fields are `id`, `title`. You can include multiple options by separating them with a comma.

Custom Query Builder class

When you want to encapsulate the logic in a query class, you can do this by extending Spatie\QueryBuilder\QueryBuilder and configuring your query builder in a constructor.

This approach can be seen in Spatie’s Laravel Query Builder documentation, in a video about building Mailcoach.

Here is the example from this video and the resulting documentation. Here Laravel Query Builder is used for the API request params, and Laravel Data for the response.

<?php
namespace App\Queries;
use Spatie\QueryBuilder\AllowedFilter;
use Spatie\QueryBuilder\QueryBuilder;
// ...
class EmailListSubscribersQuery extends QueryBuilder
{
public function __construct(EmailList $list)
{
$query = EmailListSubscriber::query()
->where('email_list', $list->id);
parent::__construct($query);
$this
->allowedSorts('created_at', 'unsubscribed_at', 'email', 'first_name', 'last_name')
->allowedFilters([
/**
* Fuzzy search subscribers by `email`, `first_name`, `last_name`, and the assigned tags `name`.
*/
AllowedFilter::custom('search', new FuzzyFilter([
'email',
'first_name',
'last_name',
'tags.name',
]))
]);
}
}
Resulting documentation
Get email list subscribers
get
https://companies.app/api/email-list-subscribers
List all the email list subscribers.
Request
query Params
per_page
integer
Default
15
filter[search]
string
Fuzzy search subscribers by `email`, `first_name`, `last_name`, and the assigned tags `name`.
sort
string
Available sorts are `created_at`, `unsubscribed_at`, `email`, `first_name`, `last_name`. You can sort by multiple options by separating them with a comma. To sort in descending order, use `-` sign in front of the sort, for example: `-created_at`.
Responses
200
·
OK
The paginated collection of `EmailListSubscriber`
Body
object
data
EmailListSubscriber[]
required
The list of items
- Hide properties
id
number
required
first_name
string
required
last_name
string
required
email
string<email>
required
unsubscribed_at
string or null
required
created_at
string
required
links
object[]
required
Generated paginator links.
+ Show properties
meta
object
required
+ Show properties
Scramble PRO
Comprehensive API documentation generation for Spatie’s Laravel Data and Laravel Query Builder.