Introduction

The Streams Plugin is the primary plugin shipped with the Streams Platform.

Installation

The Streams Plugin is shipped inside the Streams Platform.

Usage

This section will go over how to use the built-in plugin that comes with the Streams Platform.

Mapping functions to services

The streams plugin leverages function mapping to handle defining multiple functions within the same object.

For example all functions called that start with agent_ will be mapped to the \Jenssegers\Agent\Agent class. When function mapping is being used the suffix will be camel cased into a method name.

For example agent_is_mobile() becomes $agent->isMobile() and any parameters are passed along accordingly.

Addon

The addon functions provide access to the \Anomaly\Streams\Platform\Addon\AddonCollection.

addon

The addon function returns a decorated addon instance.

Returns: \Anomaly\Streams\Platform\Addon\AddonPresenter
Arguments
Key Required Type Default Description

$identifier

true

string

none

The slug or dot namespace of the addon.

Twig
// Specify as a dot namespace.
{{ addon('anomaly.module.users').name }} // Users Module

// Or you can pass the
// slug if it's unique.
{{ addon('pages').name }} // Users Module

addons

The addons method returns a decorated collection of addons.

Returns: \Anomaly\Streams\Platform\Addon\AddonCollection
Arguments
Key Required Type Default Description

type

false

string

null

The type of addons to return.

Twig
{{ addons() }} // A collection of all addons.

// A collection of all modules.
{% for module in addons('modules') %}
    <p>{{ module.name }} is enabled.</p>
{% endfor %}

Agent

The agent_* functions map directly to the \Jenssegers\Agent\Agent class.

{{ agent_is("iPhone") }} // boolean

{{ agent_is_mobile() }} // boolean

{{ agent_platform() }} // "OS X"

For more information on usage refer to the jenssegers/agent documentation.

Asset

The asset_* functions map directly to the ``Anomaly\Streams\Platform\Asset\Asset` class. For more information on usage please refer to asset documentation.

{{ asset_add("theme.js", "theme::js/vendor/*") }}
{{ asset_add("theme.js", "theme::js/libraries/sortable.js", ["min"]) }}

{{ asset_script("theme.js", ["min"]) }}

{% for script in asset_scripts("scripts.js") %}
    {{ script|raw }}
{% endfor %}

Including javascript constants

The constants function returns a number of required javascript constants necessary for field types and potentially other components to work correctly. Make sure you include it in your themes!

{{ constants() }}

Example of the included JavaScript constants:

<script type="text/javascript">

    var APPLICATION_URL = "{{ url() }}";
    var APPLICATION_REFERENCE = "{{ env('APPLICATION_REFERENCE') }}";
    var APPLICATION_DOMAIN = "{{ env('APPLICATION_DOMAIN') }}";

    var CSRF_TOKEN = "{{ csrf_token() }}";
    var APP_DEBUG = "{{ config_get('app.debug') }}";
    var APP_URL = "{{ config_get('app.url') }}";
    var REQUEST_ROOT = "{{ request_root() }}";
    var REQUEST_ROOT_PATH = "{{ parse_url(request_root()).path }}";
    var TIMEZONE = "{{ config_get('app.timezone') }}";
    var LOCALE = "{{ config_get('app.locale') }}";
</script>

Auth

The auth_* functions provide limited access to the \Illuminate\Contracts\Auth\Guard class.

{% if auth_check() %}
    Hello {{ auth_user().display_name }}!
{% endif %}

{% if auth_guest() %}
    Welcome guest!
{% endif %}

Breadcrumb

The breadcrumb functions returns the \Anomaly\Streams\Platform\Ui\Breadcrumb\BreadcrumbCollection.

You can use this function to automatically generate a Bootstrap 3/4 breadcrumb:

{{ breadcrumb() }} // Returns Bootstrap breadcrumb

You can use the same function to generate your own breadcrumb:

<ol class="breadcrumb">
    {% for breadcrumb, url in breadcrumb() %}
        {% if loop.last %}
            <li class="breadcrumb-item active">{{ trans(breadcrumb) }}</li>
        {% else %}
            <li class="breadcrumb-item"><a href="{{ url }}">{{ trans(breadcrumb) }}</a></li>
        {% endif %}
    {% endfor %}
</ol>

Carbon

The carbon function provides access to the \Carbon\Carbon class.

Returns: /Carbon/Carbon
Arguments
Key Required Type Default Description

$time

false

string

null

A date/time string.

$timezone

false

string

Configured default timezone.

A timezone string.

Twig
{{ carbon().today() }} // 2016-06-24 00:00:00

{{ carbon('-1 day', config('app.timezone')) }} // "2016-08-17 15:05:26"

{{ carbon('-1 day', config('app.timezone')).diffInHours() }} // 24

Config

The config functions provide limited access to the \Illuminate\Contracts\Config\Repository class.

{{ config_get("app.name") }} // PyroCMS

{{ config_get("streams::locales.default") }} // en

{{ config_has("foo") }} // boolean

CSRF

The CSRF functions provide access to CSRF information.

csrf_token

The csrf_token method returns the CSRF token value.

Returns: string
Twig
{{ csrf_token() }} // The CSRF token

csrf_field

The csrf_field method returns the name of the CSRF field.

Returns: string
Twig
{{ csrf_field() }} // The CSRF field name

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
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', '[email protected]%')
    .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
{% 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
{% 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
{% admin = entries('roles', 'users').findBy('slug', 'admin') %}

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

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
{% activate = 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
{% 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
{% 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
{% 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
{% 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
{% 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
{% 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,
];

Env

You can access environmental values with the env function. This function behaves just like the Laravel helper function.

{% if env("APP_DEBUG") %}
    You are debugging!
{% endif %}

Footprint

The footprint functions provide information about load time and footprint.

request_time

The request_time function returns the elapsed time for the request.

Returns: float
Arguments
Key Required Type Default Description

$decimal

false

integer

2

The number of decimals to return.

Twig
{{ request_time(3) }} // 0.551

memory_usage

The memory_usage function returns the memory used by the request.

Returns: string
Arguments
Key Required Type Default Description

$precision

false

integer

1

The number of decimals to return.

Twig
{{ memory_usage() }} // 6.5 m

Request

The request_* functions map directly to the \Illuminate\Http\Request class.

For more information on usage please refer to documentation for requests in Laravel.

{{ request_get("foo") }} // bar

{{ request_method() }} // GET

{{ request_root() }} // http://domain.com/

{{ request_segment(1) }} // foo

{{ request().route('id') }} // 123

Session

The session_* functions provide limited access to the \Illuminate\Session\Store class.

{{ session_get("foo") }} // "bar"

{{ session_pull("foo") }} // "bar"
{{ session_pull("foo") }} // null

{{ session_has("foo") }} // boolean

String

The str_* functions map directly to the \Anomaly\Streams\Platform\Support\Str class which extends Laravel's \Illuminate\Support\Str class.

For more information on usage please refer to the String service.

{{ str_humanize("hello_world") }} // "Hello World"

{{ str_truncate(string, 100) }}

{% if str_is("*.module.*", addon("users").namespace) %}
    That's a valid module namespace!
{% endif %}

{{ str_camel("some_slug") }} // "someSlug"

{{ str_studly("some_slug") }} // "SomeSlug"

{{ str_random(10) }} // 4sdf87yshs

Translator

The translator_* functions provide access to the \Illuminate\Translation\Translator class.

{{ trans("anomaly.module.users::addon.name") }} // "Users Module"

{{ trans_exists("anomaly.module.users::field.bogus.name") }} // boolean

URL

The url_* functions map directly to the \Illuminate\Contracts\Routing\UrlGenerator.

You can also refer to Laravel URL helpers for more information.

{{ url_to("example") }} // "http://domain.com/example"

{{ url_secure("example") }} // "https://domain.com/example"

{{ url_route("anomaly.module.users::password.forgot") }} // "users/password/forgot"

View

View functions help leverage the view engine.

view

The view function returns a rendered view.

The single most important detail of this function versus using Twig's include is that the view is passed through the view composer in order to allow overriding. Overriding on the other hand is not supported with the include tag.

Returns: string
Arguments
Key Required Type Default Description

$view

true

string

none

The view you wish to render.

$data

false

array

null

The data to pass along to the view.

Twig
{{ view('example.module.test::example/view', {'foo': 'Bar'}) }}

parse

The parse function parses a string template.

Returns: string
Arguments
Key Required Type Default Description

$template

true

string

none

The template string to parse.

$data

false

array

null

The data to pass along to the view.

Twig
{{ parse("This is a template {{ foo }}", {"foo": "bar"}) }}

layout

The layout method checks for a theme layout and returns a default if it's not found.

Returns: string
Arguments
Key Required Type Default Description

$layout

true

string

none

The layout to look for.

$default

false

string

default

The default layout to fallback to.

Twig
{% extends layout("posts") %} // extends "theme::layotus/default" if not found