Retrieving results
You may use the query method on a number of repository classes to begin a query. This method returns a fluent query builder instance for the given item, allowing you to chain more constraints onto the query then get the results using the get method.
For example, here’s how you could get all the entries:
Statamic\Facades\Entry::query()->get();
This would typically return a Collection of the items. In this case, it’d be full of Entry objects.
Filtering results
In the example above, you may notice it’s exactly the same as running Entry::all(). The power of using the query builder is to let you chain more complex restraints onto it. For instance, you could filter down the items.
You may use the where method to add simple where clauses:
Entry::query()
->where('collection', 'blog')
->where('food', 'bacon')
->get();
You may use the whereIn method to check against an array of values:
Entry::query()
->whereIn('food', ['bacon', 'cheese'])
->get();
Filtering by taxonomies
If you want to filter by a taxonomy term, you can use whereTaxonomy. For instance:
Entry::query()
->whereTaxonomy('tags::harry-potter');
Ordering, Limit, and Offset
The orderBy method allows you to sort by a given field:
Entry::query()->orderBy('title', 'desc')->get();
You may limit and/or skip results by using the limit and offset methods:
Entry::query()->offset(5)->limit(5)->get();
Aggregates
The count method allows you to get the number of records.
Entry::query()->count();
Pagination
You may paginate a result set by finishing your query with the paginate method.
Entry::query()->paginate(15);
This will return an instance of Illuminate\Pagination\LengthAwarePaginator.
Available Query Builders
Assets
Query against all assets.
Statamic\Facades\Asset::query()
->where('container', 'main')
->where('folder', 'images')
->where('alt', 'like', '%potato%')
->get();
The container and folder columns will allow you to refine the location of the assets, where any other column will filter from asset data values.
Asset Container Assets
Query against all assets in a particular container. Similar to the above query, but with the container already implied.
Statamic\Facades\AssetContainer::find('main')
->queryAssets()
->where('folder', 'images')
->get();
Entries
Query against all entries.
Statamic\Facades\Entry::query()
->where('title', 'like', '%hello%')
->get();
Collection Entries
Query against entries in a particular collection. Similar to the above query, but with the container already implied.
Statamic\Facades\Collection::find('blog')
->queryEntries()
->where('title', 'like', '%news%')
->get();
Global Fields
Get access to Global fields from your PHP files.
use Statamic\Facades\GlobalSet;
GlobalSet::findByHandle('footer')
->inCurrentSite()
->get('copyright');
Users
Query against all users.
Statamic\Facades\User::query()
->where('email', '[email protected]')
->first();
User Group Users
Query against users in a particular user group. Similar to the above query, but with the group already implied.
Statamic\Facades\UserGroup::find('admin')
->queryUsers()
->where('mustache', true)
->get();
Caveats
The Statamic query builder are similar to Laravel’s Eloquent and database query builders, but they are not entirely the same.
Where the Laravel query builders would translate to SQL under the hood, the Statamic equivalent ones may not. So, for instance, you cannot use features such a raw SQL expressions, joins, etc.
If you have re-bound a particular repository or query builder to an Eloquent equivalent, you may be able to use these features, however if you intend to distribute it in an addon, keep in mind that not everyone may be using a database.