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>
**Pro Tip:** The entry criteria is extendable! To learn how to add your own functionality to queries refer to the criteria documetation.
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() %}
**Note:** To use a custom criteria you must provide a **model** because the model returns it's criteria.

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() %}
**Note:** Cache automatically invalidates itself when any entry in the stream is modified.
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,
];