---
title: Asset
---

# Asset

<div class="documentation__toc"></div>

@TODO remove Laravel links to preserve version integrity

The `\Anomaly\Streams\Platform\Asset\Asset` class built over the [Assetic](https://github.com/kriswallsmith/assetic) framework by [Kris Wallsmith](http://kriswallsmith.net/) provides a fluent API for managing collections of assets.

It can be used both in the API:

```php
app(\Anomaly\Streams\Platform\Asset\Asset::class)
    ->add('theme.css', 'theme::example/text.less')
    ->add('theme.css', 'theme::example/foo.less')
    ->path(); // Returns the path of the concatenated theme.css file.
```

And also in Twig:

```twig
{{ asset_add("theme.css", "theme::less/fonts/fonts.less") }}
{{ asset_add("theme.css", "theme::less/theme/theme.less") }}
{{ asset_add("build.css", "theme::scss/theme/theme.scss") }}

{{ asset_add("theme.js", "theme::js/libraries/jquery.min.js") }}
{{ asset_add("theme.js", "theme::js/libraries/tether.min.js") }}
{{ asset_add("theme.js", "theme::js/libraries/bootstrap.min.js") }}
{{ asset_add("theme.js", "theme::js/libraries/prism.min.js") }}
{{ asset_add("theme.js", "theme::js/libraries/mark.min.js") }}
{{ asset_add("theme.js", "theme::js/theme/*") }}

{{ asset_style("theme.css", ["min"]) }}
{{ asset_style("build.css", ["live"]) }}

{% for style in asset_styles("styles.css") %}
    {{ style|raw }}
{% endfor %}

{{ asset_script("theme.js") }}
```

## Introduction

This section will introduce you to the `Asset` class and and how to use it.

### Assets

An asset is a file with _filterable_ content that can be loaded and dumped.

### Collections

Collections are used to organize the assets you are working with. Assets in a collection can be combined or used individually.

> Collections are _always_ named such that it reflects the desired output name.{.tip}

```php
$asset->add("collection.css", "theme::example.scss");
$asset->add("collection.js", "theme::example.js");
```

### Filters

Filters are used to mutate the content of the assets.

> Filters can be applied to individual assets in a collection as well as the entire collection.{.notice}

```php
$asset->add("collection.css", "theme::example.scss", ["min", "live"]);
```

### Available Filters

*   `min`: minifies content
*   `less`: parses LESS into CSS
*   `styl`: parses STYL into CSS
*   `scss`: parses SCSS into CSS
*   `parse`: parses content with Twig
*   `coffee`: compiles CoffeeScript into Javascript
*   `embed`: embeds image data in your stylesheets
*   `live`: refreshes content when LIVE_ASSETS is enabled
*   `version`: appends an automated version ID to the published path

```php
$asset->path('theme.css', ['version']);
```

```php
{{ asset_style('theme.css', ['version']) }}
```

#### Automatic Filters

`scss`, `less`, `styl`, and `coffee` filters are are applied automatically to matching files.

You may wish to use files that use an alternate syntax like LESS for CSS or Coffee for Javascript. In most cases you do not need to manually add filters to compile these assets to relevant syntax for output. Simply add them along with your other assets.

```php
$asset
    ->add('theme.css', 'example::styles/example.css')
    ->add('theme.css', 'example::styles/example.less')
    ->add('theme.css', 'example::styles/example.scss')
    ->add('theme.css', 'example::styles/example.styl');
```

```php
{{ asset_add('theme.css', 'example::styles/example.css') }}
{{ asset_add('theme.css', 'example::styles/example.less') }}
{{ asset_add('theme.css', 'example::styles/example.scss') }}
{{ asset_add('theme.css', 'example::styles/example.styl') }}
```

### Path Hints

To avoid having to use full paths to your assets there are a number of path hints available. Hints are a namespace that prefixes the asset path.

    "theme::js/initialize.js" // path-to-your-active-theme/resources/js/initialize.js

    "anomaly.module.products::js/initialize.js" // path-to-products-module/resources/js/initialize.js

### Available Path Hints

> [We list all the available path hints for assets in the reference section.](../reference/hints#asset-hints){.link}

### Registering Path Hints

Registering path hints is easy. Just inject the `\Anomaly\Streams\Platform\Asset\Asset` class into your service provider or function and use the `addPath` method:

```php
$asset->addPath("foo", base_path("example/path"));
```

Now you can use that path:

```php
{{ asset_add('foo::example/test.js') }}
```

## Configuration

Configuration can be found in the Streams Platform under `config/resources/assets.php`. You can publish the Streams Platform with `php artisan streams:publish` to override configuration or use `.env` variables to control them as available.

##### Configuring additional path hints

You can configure additional path hints for the asset service with the `streams::assets.paths` configuration value:

```php
'paths' => [
    'example' => 'some/local/path',
    's3'      => 'https://region.amazonaws.com/bucket'
]
```

You can now use these hints just like all the others:

```php
{{ asset_add('theme.js', 'example::example/test.js') }}
```

### Configuring additional output hints

Output hints help the system interpret the correct output file extension for an asset. For example the hint for `.less` is `.css`:

```php
'hints' => [
    'css' => [
        'less',
        'scss',
        'sass',
        'styl',
    ],
    'js'  => [
        'coffee',
    ],
]
```

### Configuring compilers

By default Pyro leverages PHP compilers. You can opt into other compilers if you like:

```php
'filters' => [
    'less' => env('LESS_COMPILER', 'php'),
    'sass' => env('SASS_COMPILER', 'php'),
]
```

### Forcing asset compiling

You can force assets with the `live` filter to compile for every page load by defining the `LIVE_ASSETS` flag. This is helpful during development to control assets that change often:

```php
'live' => env('LIVE_ASSETS', false)
```

Use `true` to compile all live assets. Use `admin` to compile all live admin assets. Use `public` to compile all live public assets.

### Named Assets

Sometimes it's necessary to include assets in your addon that may be duplicated by other addons that share the library or script. You can name your assets to prevent further loading of the same assets elsewhere with the `as:*` filter. Named assets are unique across all collections.

```twig
{{ asset_add("styles.css", "anomaly.field_type.select::scss/choices.scss", ["as:jshjohnson/Choices.css"]) }}
{{ asset_add("scripts.js", "anomaly.field_type.select::js/choices.min.js", ["as:jshjohnson/Choices.js"]) }}
```

> The name provided is forced lowercase internally to normalize names.{.tip}

### Required Assets

You can force named assets to be included by using the `required` filter if needed. This is helpful if a static collection includles the library that may be included dynaically later.

```twig
{{ asset_add(
    "build.css",
    "pyrocms.theme.accelerant::scss/theme/theme.scss",
    [
        "required",
        "as:t4t5/sweetalert.css",
        "as:jshjohnson/Choices.css",
        "as:rstacruz/nprogress.css",
    ]
) }}
```

## Basic Usage

Inject the `Anomaly\Streams\Platform\Asset\Asset` class into your own class or method to get started. You can also use the Streams Plugin to interact with the asset class.

### Asset::add()

The `add` method let's you add a single asset or glob pattern of assets to a collection.

#### Returns: `Anomaly\Streams\Platform\Asset\Asset`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$collection

</td>

<td>

true

</td>

<td>

string

</td>

<td>

none

</td>

<td>

The collection to add the asset to.

</td>

</tr>

<tr>

<td>

$file

</td>

<td>

true

</td>

<td>

string

</td>

<td>

none

</td>

<td>

The file or glob pattern to add to the collection.

</td>

</tr>

<tr>

<td>

$filters

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

An array of filters to apply to the single asset or pattern.

</td>

</tr>

</tbody>

</table>

#### Example

    $asset->add('theme.css', 'theme::css/*', ['parse']);

#### Twig

    {{ asset_add('theme.css', 'theme::css/*', ['parse']) }}

### Asset::download()

The `download` method lets you cache a remote resource on your server. This might be an edge case scenario but it sure it handy when you need it!

#### Returns: `string`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$url

</td>

<td>

true

</td>

<td>

string

</td>

<td>

none

</td>

<td>

The url to add the remote asset.

</td>

</tr>

<tr>

<td>

$ttl

</td>

<td>

false

</td>

<td>

integer

</td>

<td>

3600

</td>

<td>

The number of seconds to cache the resource for.

</td>

</tr>

<tr>

<td>

$path

</td>

<td>

false

</td>

<td>

string

</td>

<td>

{host}/{filename}

</td>

<td>

The path in downloads to put the cached asset.

</td>

</tr>

</tbody>

</table>

#### Example

    $path = $asset->download('http://shakydomain.com/js/example.js', 60*60*24);

    $asset->add('theme.js', $path);

#### Twig

    {{ asset_add('theme.js', asset_download('http://shakydomain.com/js/example.js', 60*60*24)) }}

### Asset::inline()

The `inline` method returns the contents of a collection for including inline or dumping from a controller response.

#### Returns: `string`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$collection

</td>

<td>

true

</td>

<td>

string

</td>

<td>

none

</td>

<td>

The collection return contents of.

</td>

</tr>

<tr>

<td>

$filters

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

The filters to apply to the collection.

</td>

</tr>

</tbody>

</table>

#### Example

    echo $asset->inline('theme.js', ['min']);

#### Twig

    <script type="text/javascript">
        {{ asset_inline('theme.js', ['min']) }}
    </script>

### Asset::url()

The `url` method returns the full URL to the collection output file.

#### Returns: `string`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$collection

</td>

<td>

true

</td>

<td>

string

</td>

<td>

null

</td>

<td>

The collection return the URL for.

</td>

</tr>

<tr>

<td>

$filters

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

An array of filters to apply to the entire collection.

</td>

</tr>

<tr>

<td>

$parameters

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

Query string parameters to append to the URL.

</td>

</tr>

<tr>

<td>

$secure

</td>

<td>

false

</td>

<td>

boolean

</td>

<td>

true or false depending on if current request is HTTP/HTTPS.

</td>

<td>

Whether to return HTTP or secure HTTPS URL.

</td>

</tr>

</tbody>

</table>

#### Example

    $asset->url('theme.js', ['min']);

#### Twig

    <script type="text/javascript" src="{{ asset_url('theme.js', ['min']) }}"></script>

### Asset::path()

The `path` method returns the URL path to the collection output file.

#### Returns: `string`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$collection

</td>

<td>

true

</td>

<td>

string

</td>

<td>

null

</td>

<td>

The collection return the URL for.

</td>

</tr>

<tr>

<td>

$filters

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

An array of filters to apply to the entire collection.

</td>

</tr>

</tbody>

</table>

#### Example

    $asset->path('theme.js');

#### Twig

    <script type="text/javascript" src="{{ asset_path('theme.js') }}"></script>

### Asset::asset()

The `asset` method returns the `path` with the root prefix included. This is helpful if you are installed and serving from a directory and not a virtual host.

#### Returns: `string`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$collection

</td>

<td>

true

</td>

<td>

string

</td>

<td>

null

</td>

<td>

The collection return the URL for.

</td>

</tr>

<tr>

<td>

$filters

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

An array of filters to apply to the entire collection.

</td>

</tr>

</tbody>

</table>

#### Example

    $asset->asset('theme.js');

#### Twig

    <script type="text/javascript" src="{{ asset_asset('theme.js') }}"></script>

### Asset::script()

The `script` method returns a `<script>` tag including the collection output file.

#### Returns:

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$collection

</td>

<td>

true

</td>

<td>

string

</td>

<td>

null

</td>

<td>

The collection return the tag for.

</td>

</tr>

<tr>

<td>

$filters

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

An array of filters to apply to the entire collection.

</td>

</tr>

<tr>

<td>

$attributes

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

A `key=>value` array of tag attributes.

</td>

</tr>

</tbody>

</table>

#### Example

    $asset->script('theme.js', ['parse']);

#### Twig

    {{ asset_script('theme.js', ['parse']) }}

You can also pass the URL of an arbitrary asset to include it as well.

    {{ asset_script('public::example/test.js') }}

### Asset::style()

The `style` method returns a `<link>` tag linking the collection output file.

#### Returns: `<link type="text/css" rel="stylesheet" href="{path}" {attributes}="">`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$collection

</td>

<td>

true

</td>

<td>

string

</td>

<td>

null

</td>

<td>

The collection return the tag for.

</td>

</tr>

<tr>

<td>

$filters

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

An array of filters to apply to the entire collection.

</td>

</tr>

<tr>

<td>

$attributes

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

A `key=>value` array of tag attributes.

</td>

</tr>

</tbody>

</table>

#### Example

    $asset->style('theme.css', ['min'], ['media' => 'print']);

#### Twig

    {{ asset_style('theme.css', ['min'], ['media' => 'print']) }}

You can also pass the URL of an arbitrary asset to include it as well.

    {{ asset_style('public::example/test.css') }}

### Asset::scripts()

The `scripts` method return an array of `<script>` tags for each asset added to the collection.

#### Returns: `array`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$collection

</td>

<td>

true

</td>

<td>

string

</td>

<td>

null

</td>

<td>

The collection return the asset tags for.

</td>

</tr>

<tr>

<td>

$filters

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

An array of filters to apply to each asset.

</td>

</tr>

<tr>

<td>

$attributes

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

A `key=>value` array of tag attributes.

</td>

</tr>

</tbody>

</table>

#### Example

    $asset->scripts('scripts.js');

#### Twig

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

> Addons leverage the **scripts.js** collection for per page inclusion of assets. Be sure to include it in your theme!{.notice}}

### Asset::styles()

The `styles` method returns an array of `<link>` tags for each asset in the collection.

#### Returns: `array`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$collection

</td>

<td>

true

</td>

<td>

string

</td>

<td>

null

</td>

<td>

The collection return asset tags for.

</td>

</tr>

<tr>

<td>

$filters

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

An array of filters to apply to each asset.

</td>

</tr>

<tr>

<td>

$attributes

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

A `key=>value` array of tag attributes.

</td>

</tr>

</tbody>

</table>

#### Example

    $asset->styles('theme.css', ['min']);

#### Twig

    {% for style in styles('theme.css', ['min']) %}
        {{ style|raw }}
    {% endfor %}

> Addons leverage the **styles.css** collection for per page inclusion of assets. Be sure to include it in your theme!{.notice}

### Asset::paths()

The `path` method returns an array of URL paths for each asset in the collection.

#### Returns: `array`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$collection

</td>

<td>

true

</td>

<td>

string

</td>

<td>

null

</td>

<td>

The collection return the asset paths for.

</td>

</tr>

<tr>

<td>

$filters

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

An array of filters to apply to each asset.

</td>

</tr>

</tbody>

</table>

#### Example

    $asset->paths('styles.css');

#### Twig

    {% for path in asset_paths('styles.css') %}
        {{ html_style(path) }}
    {% endfor %}

### Asset::urls()

The `urls` method returns an array of URLs for each asset in the collection.

#### Returns: `array`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$collection

</td>

<td>

true

</td>

<td>

string

</td>

<td>

null

</td>

<td>

The collection return the URL asset paths for.

</td>

</tr>

<tr>

<td>

$filters

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

An array of filters to apply to the each asset.

</td>

</tr>

<tr>

<td>

$parameters

</td>

<td>

false

</td>

<td>

array

</td>

<td>

null

</td>

<td>

Query string parameters to append to all URLs.

</td>

</tr>

<tr>

<td>

$secure

</td>

<td>

false

</td>

<td>

boolean

</td>

<td>

true or false depending on if current request is HTTP/HTTPS.

</td>

<td>

Whether to return HTTP or secure HTTPS URLs.

</td>

</tr>

</tbody>

</table>

#### Example

    $asset->urls('styles.css');

#### Twig

    {% for url in asset_urls('styles.css') %}
        {{ html_style(url) }}
    {% endfor %}

### Asset::addPath()

The `addPath` let's you register your own path hint. This is generally done during the boot process. You can hint local path and remote paths.

#### Returns: `Anomaly\Streams\Platform\Asset\Asset`

#### Arguments

<table class="table table-bordered table-striped">

<thead>

<tr>

<th>Key</th>

<th>Required</th>

<th>Type</th>

<th>Default</th>

<th>Description</th>

</tr>

</thead>

<tbody>

<tr>

<td>

$namespace

</td>

<td>

true

</td>

<td>

string

</td>

<td>

none

</td>

<td>

The path hint.

</td>

</tr>

<tr>

<td>

$path

</td>

<td>

true

</td>

<td>

string

</td>

<td>

none

</td>

<td>

The path the hint is refercing.

</td>

</tr>

</tbody>

</table>

#### Example

    $asset
        ->addPath('example', 'some/local/path')
        ->addPath('s3', 'https://region.amazonaws.com/bucket');

    $asset->style('s3::styles.css');

#### Artisan Commands

The asset service comes with Artisan support.

##### Clearing Asset Cache

You can use the `asset:clear` command to clear the asset cache files.

    php artisan asset:clear
