Entries

Entries

The entries and query functions provide you with a convenient, fluent interface to fetch streams and non-streams database records respectively.

Introduction

The Streams Platform comes with a clean, extendable, fluent API for building database queries within the view layer.

entries

The entries function starts a model criteria query for database records powered by Streams. Being that nearly everything in PyroCMS is a stream this is your primary entry point to retrieving database records.

Returns: \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$namespace	true	string	none	The stream namespace.
$slug	false	string	The namespce provided.	The stream slug.

Twig

<ul>
    {% for category in entries('posts', 'categories').get() %}
    <li>
        {{ category.slug }}
    </li>
    {% endfor %}
</ul>

query

The query function starts a model criteria query for database records that are not powered by Streams though it works all the same for Streams powered database records.

Returns: \Anomaly\Streams\Platform\Model\EloquentCriteria

Arguments

Key	Required	Type	Default	Description
$model	false	string	null	The model to start the query from.

Twig

{% set users = query()
    .from('test_table')
    .where('active', true)
    .get() %}

// Using a model
{% set users = query('App\Example\TestModel')
    .where('active', true)
    .get() %}

Retrieving Results

This section will show you how to return results from the model criteria returned by entries and query functions.

Retrieving A Single Row

If you just need to retrieve a single entry, you may use the first method. This method will return a single \Anomaly\Streams\Platform\Entry\EntryPresenter:

{% set user = entries('users').where('display_name', 'Ryan Thompson').first() %}

{{ user.email }}

EloquentCriteria::get()

The get method returns the results of the query.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCollection or \Anomaly\Streams\Platform\Entry\EntryCollection

Arguments

Key	Required	Type	Default	Description
$columns	false	array	["*"]	The columns to select.

Twig

{% set users = entries('users', 'users')
    .where('email', 'LIKE', '%@gmail.com%')
    .where('activated', true)
    .get() %}

{% for user in users %}
    {{ user.display_name }}
{% endfor %}

EloquentCriteria::first()

The first method returns the first matching query result.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentPresenter or \Anomaly\Streams\Platform\Entry\EntryPresenter

Arguments

Key	Required	Type	Default	Description
$columns	false	array	["*"]	The columns to select.

Twig

{% set user = entries('users').where('display_name', 'Ryan Thompson').first() %}

{{ user.email }}

EloquentCriteria::find()

The find method allows you to return a single record by it's ID.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentPresenter or \Anomaly\Streams\Platform\Entry\EntryPresenter

Arguments

Key	Required	Type	Default	Description
$identifier	true	integer	none	The ID of the result to return.
$columns	false	array	["*"]	The columns to select.

Twig

{% set user = entries('users').find(1) %}

{{ user.email.mailto|raw }}

EloquentCriteria::paginate()

The paginate method returns the result of the entries and query functions as a pagination object.

Returns: \Illuminate\Pagination\LengthAwarePaginator

Arguments

Key	Required	Type	Default	Description
$perPage	false	string	15	The number of entries per page.
$columns	false	array	["*"]	The columns to select.

Twig

{% set posts = entries('posts').paginate() %}

{% for post in posts %}
    <p>
        {{ post.title }}
    </p>
{% endfor %}

{{ posts.links|raw }}

EloquentCriteria::findBy()

The findBy by method allows you to find a single query result by a column value. This comes in handy for finding records by slug for example.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentPresenter or \Anomaly\Streams\Platform\Entry\EntryPresenter

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The column to test.
$value	true	mixed	none	The value to test the column by.
$columns	false	array	["*"]	The columns to select.

Twig

{% set admin = entries('roles', 'users').findBy('slug', 'admin') %}

// You can also map the column into the method name.
{% set admin = entries('roles', 'users').findBySlug('admin') %}

EloquentCriteria::cache()

The cache method sets the cache TTL for the query.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$ttl	true	int	none	The maximum time in seconds to cache results for.

Twig

// Cache for a maximum of 300 seconds
{% set books = entries('library', 'books').cache(300).get() %}

EloquentCriteria::fresh()

The fresh method forces non-cached results to be returned.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Twig

{% set books = entries('library', 'books').fresh().get() %}

Aggregates

The model criteria also provide a variety of aggregate methods such as count, max, min, avg, and sum. You can call any of these methods after constructing your query.

EloquentCriteria::count()

The count method returns the total number of query results.

Returns: integer

Arguments

Key	Required	Type	Default	Description
$columns	false	array	["*"]	The collection to add the asset to.

Twig

{% set activated = entries('users').where('activated', true).count() %}

EloquentCriteria::sum()

The sum method returns the sum of the column value.

Returns: integer

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The column to summarize.

Twig

{% set orders = entries('store', 'orders').where('finalized', true).sum('subtotal') %}

EloquentCriteria::max()

The max method returns the highest column value.

Returns: mixed

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The column to find the max for.

Twig

{% set price = entries('store', 'products').where('enabled', true).max('price') %}

EloquentCriteria::min()

The min method returns the lowest column value.

Returns: mixed

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The column to find the min for.

Twig

{% set price = entries('store', 'products').where('enabled', true).min('price') %}

EloquentCriteria::avg()

The avg method returns the average value of the column.

Returns: integer

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The column to average.

Twig

{% set mean = entries('store', 'products').where('enabled', true).avg('price') %}

Where Clauses

This section will go over where clauses for the entries and query model criteria functions.

EloquentCriteria::where()

The where method adds a where clauses to the query. The most basic call to where requires three arguments. The first argument is the name of the column. The second argument is an operator, which can be any of the database's supported operators. Finally, the third argument is the value to evaluate against the column.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column.
$operator|$value	true	string	none	The where operator.
$value	false	string	null	The value if an operator is defined.

Twig

// Example that verifies the value of the "votes" column is equal to 100:
{% set users = entries('users').where('votes', '=', 100).get() %}

// Assuming the "=" operator.
{% set users = entries('users').where('votes', 100).get() %}

EloquentCriteria::orWhere()

You may chain where constraints together as well as add or where clauses to the query.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column.
$operator|$value	true	string	none	The where operator.
$value	false	string	null	The value if an operator is defined.

Twig

{% set = users = entries('users')
    .where('votes', '>', 100)
    .orWhere('name', 'John')
    .get() %}

EloquentCriteria::whereBetween()

The whereBetween method verifies that a column's value is between two values.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column.
$values	true	array	none	The values to test the column against.

Example

{% set users = entries('users').whereBetween('votes', [1, 100]).get() %}

EloquentCriteria::whereNotBetween()

The whereNotBetween method verifies that a column's value lies outside of two values.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column.
$values	true	array	none	The values to test the column against.

Twig

{% set users = entries('users').whereNotBetween('votes', [1, 100]).get() %}

EloquentCriteria::whereIn()

The whereIn method verifies that a given column's value is contained within the given array.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column.
$values	true	array	none	The array of values to find.

Twig

{% set users = entries('users').whereIn('id', [1, 2, 3]).get() %}

EloquentCriteria::whereNotIn()

The whereNotIn method verifies that a given column's value is not contained within the given array.

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column.
$values	true	array	none	The array of values to exclude.

Twig

{% set users = entries('users').whereNotIn('id', [1, 2, 3]).get() %}

EloquentCriteria::whereNull()

The whereNull method verifies that the value of the given column is NULL.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column.

Twig

{% set users = entries('users').whereNull('updated_at').get() %}

EloquentCriteria::whereNotNull()

The whereNotNull method verifies that the column's value is not NULL.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column.

Twig

{% set users = entries('users').whereNotNull('updated_at').get() %}

EloquentCriteria::whereDate()

The whereDate method may be used compare a column's value against a date.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column.
$operator|$value	true	string	none	The where operator.
$value	false	string	null	The value if an operator is defined.

Twig

{% set users = entries('users').whereDate('created_at', '2016-10-10').get() %}

EloquentCriteria::whereMonth()

The whereMonth method may be used compare a column's value against a specific month of an year.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column.
$operator|$value	true	string	none	The where operator.
$value	false	string	null	The value if an operator is defined.

Twig

{% set users = entries('users').whereMonth('created_at', '10').get() %}

EloquentCriteria::whereDay()

The whereDay method may be used compare a column's value against a specific day of a month.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column.
$operator|$value	true	string	none	The where operator.
$value	false	string	null	The value if an operator is defined.

Twig

{% set users = entries('users').whereDay('created_at', '10').get() %}

EloquentCriteria::whereYear()

The whereYear method may be used compare a column's value against a specific year.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column.
$operator|$value	true	string	none	The where operator.
$value	false	string	null	The value if an operator is defined.

Twig

{% set users = entries('users').whereYear('created_at', '2016').get() %}

EloquentCriteria::whereColumn()

The whereColumn method may be used to test two values with an operator.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column to test.
$operator|$compare	true	string	none	The test operator or the column to compare.
$compare	false	string	null	The column to compare.

Twig

// Assumes "=" operator
{% set users = entries('users').whereColumn('first_name', 'last_name').get() %}

// Use a different operator.
{% set users = entries('users').whereColumn('updated_at', '>', 'created_at').get() %}

JSON Where Clauses

Laravel supports querying JSON column types on databases that provide support for JSON column types. You can leverage this the in the criteria queries too. Currently, this includes MySQL 5.7 and Postgres. To query a JSON column, use the -> operator:

{% set users = entries('users')
    .where('options->language', 'en')
    .get() %}

{% set users = entries('users')
    .where('preferences->dining->meal', 'salad')
    .get() %}

Ordering, Grouping, Limit, & Offset

The Streams Platform supports a number of Laravel methods for ordering, grouping, limit, and offsetting records.

EloquentCriteria::orderBy()

The orderBy method allows you to sort the result of the query by a given column.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column.
$direction	true	string	none	The direction to order column values.

Twig

{% set users = entries('users').orderBy('name', 'desc').get() %}

EloquentCriteria::inRandomOrder()

The inRandomOrder method may be used to sort the query results randomly. For example, you may use this method to fetch a random record.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Twig

{% set user = entries('users').inRandomOrder().first() %}

EloquentCriteria::groupBy()

The groupBy method can be used to group the query results.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column.

Twig

{% set users = entries('users').groupBy('category').get() %}

EloquentCriteria::having()

The having method is used often in conjunction with the groupBy method.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$column	true	string	none	The name of the column.
$operator|$value	true	string	none	The where operator.
$value	false	string	null	The value if an operator is defined.

Twig

{% set users = entries('users').groupBy('account_id').having('account_id', '>', 100).get() %}

EloquentCriteria::skip()

The skip method is an alias for limit.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$offset	true	integer	none	The number of results to skip.

Twig

{% set users = entries('users').skip(10).get() %}

EloquentCriteria::offset()

The offset method skips a number of results from the query.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$number	true	integer	none	The number of results to skip.

Twig

{% set users = entries('users').offset(10).get() %}

EloquentCriteria::take()

The take method is an alias for limit.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$number	true	integer	none	The number of results to return.

EloquentCriteria::limit()

The limit method specifies the number of results to return.

Returns: \Anomaly\Streams\Platform\Eloquent\EloquentCriteria or \Anomaly\Streams\Platform\Entry\EntryCriteria

Arguments

Key	Required	Type	Default	Description
$number	true	integer	none	The number of results to return.

Twig

{% set users = entries('users').limit(5).get() %}

Searching

This section will show you how to search for results from the search criteria returned by entries and query functions.

EloquentCriteria::search()

The search method returns a new search criteria instance which can be used just like the entry and eloquent criteria.

Returns: \Anomaly\Streams\Platform\Search\SearchCriteria

Arguments

Key	Required	Type	Default	Description
$term	true	string	none	The term you would like to search for.

Twig

// The search method must be used after entries/query
{% set results = entries('users').search('gmail').get() %}

// You can still chain criteria methods after search.
{% set results = entries('users').search('gmail').where('active', true).get() %}

Searchable Models

In order to leverage model searching you must make your model searchable using the \Laravel\Scout\Searchable trait:

use \Laravel\Scout\Searchable;

For Streams entry models you can also simply define the searchable flag since the base models implement this trait already:

protected $searchable = true;

Searchable Streams

Defining Streams as searchable can be done just like a model. However you may want to include this option in your streams migration as well:

protected $stream = [
    'slug'         => 'users',
    'title_column' => 'username',
    'searchable'   => true,
    'trashable'    => true,
];