Assets

Assets are files that you want to take special care of. Special files. Files you'd like to be friends with, and invite over for dinner. They allow you attach add extra data to your files, like alt tags and captions, and can be managed with special Tags and Fieldtypes.

Overview

Assets have recently been redesigned in Statamic 2.5.
Check out the differences!

Assets can be images, videos, documents, zip files, or just about anything else you want to upload, manage, and display on your site. Assets are grouped into Containers, allowing you to keep your files organized.

Some possible Assets

Containers

Each asset container is represented by a yaml file inside site/content/assets. We call the name of that file (e.g. main.yaml) the container ID.

The container holds the details about the root location of its assets. The location can be a local folder or credentials to an Amazon S3 bucket. See the Asset Container Drivers for more detail. The container also holds any additional asset data.

You can use the wizard in the Control Panel found at Configure > Content > Assets, or use the CLI command:

php please make:asset-container

Managing Assets

Any files placed within an container’s directory will be recognized and treated as assets. Subfolders are supported. Organize however you’d like.

You can reference assets within your content by using its URL. For example:

title: Vacation to Italy
photos: 
  - /assets/vacations/italy/trevi-fountain.jpg
  - /assets/vacations/italy/colosseum.jpg

Private Containers

There’s always an exception to the rule. If you have a private container, perhaps located above webroot to protect your downloads, you’ll need to also reference the container ID in your filename. See Private Assets for more detail.

Control Panel

In the Control Panel you have a number of ways to interact with your Assets.

You can use the Asset Manager to browse, edit, manage all your Assets across all containers, in one location.

Asset Manager

You can also use the Assets fieldtype to browse, select, upload, reorder, and remove assets from your content.

Asset Fieldtype

Moving or renaming assets (either manually or through the Control Panel) will not automatically update your content, which may result in broken links. Thankfully the fix is only a Find & Replace away, right?

Templating

As assets are referenced in your content data by their URLs, you can iterate over the array directly:

{{ photos }}
  <img src="{{ value }}" />
{{ /photos }}
<img src="/assets/vacations/italy/trevi-fountain.jpg" />
<img src="/assets/vacations/italy/colosseum.jpg" />

If your YAML contains a string instead of an array, or you’d like to target a specific item in the array, you can do that too:

photo: /assets/jerky.jpg
photos:
  - /assets/bacon.jpg
  - /assets/whisky.jpg
{{ photo }}
{{ photos:1 }}
/assets/jerky.jpg
/assets/whisky.jpg

For even more control, and to use data associated with your assets, you may use the Assets Tag.

These tags will convert your URL references to Asset objects, which in turn contain all the additional data for you to use in your templates.

{{ assets:photos }}
  <img src="{{ url }}" alt="{{ alt }}" />
{{ /assets:photos }}
<img src="/assets/vacations/italy/trevi-fountain.jpg" alt="The Trevi Fountain" />
<img src="/assets/vacations/italy/colosseum.jpg" alt="The Colosseum" />

Additional asset data

You may attach data (fields) to an asset just like you would with entries or pages. This is useful for things like alt text.

In the example above, we reference {{ alt }} within the assets tag pair. The value comes from what we’ve defined in the additional data.

Additional asset data is held within the asset container file, in an assets array. The relative path of the asset should be used as the key, with an array of data as the value.

Here’s what a container might look like:

title: Main Assets
path: assets
url: /assets
assets:
  vacations/italy/trevi-fountain.jpg:
    alt: The Trevi Fountain
  vacations/italy/colosseum.jpg:
    alt: The Colosseum

When moving or renaming an asset, be sure to update its key in this array.
If you’re using the Control Panel, this will be done automatically for you.

Note: If you don’t need any additional asset data, you need nothing more than the URL reference. (That’s one of the changes that landed in Statamic 2.5 - check it out.)

Private Assets

Sometimes it’s handy to store assets that shouldn’t be freely accessible through the browser.

This means you should put the container somewhere above the webroot, which in turn means that it doesn’t have a URL, nor will any of its assets.

You can reference and access private assets with a few extra steps.

Since private assets have no URLs, you must reference them with their IDs, the container ID and the path joined by a double colon.

top_secret_stuff: 
  - confidential::docs/evil-lair-blueprints.jpg

However, you can’t iterate over top_secret_stuff directly since it doesn’t contain working URLs. If working with images you’d like to display, you can use the Glide Tag to transform it and render a copy in a public location. You can even just use the glide tag without any parameters.

{{ top_secret_stuff }}
  <img src="{{ glide:value }}" />
{{ /top_secret_stuff }}

Private assets may also have their own data which you can access using the Assets tag as mentioned earlier.

Image Manipulation

Image assets may be manipulated in a number of ways. You can alter size, color, quality, sharpness, and so on. We use Glide to power our image transformations.

Statamic provides a URL-based manipulation API through Glide. Everything runs through a manipulation route, which by default is /img. In other words, all images that start with /img/* will be manipulated.

For example, take this URL:

/img/assets/vacations/italy/trevi-fountain.jpg?w=100&h=100
  • Statamic sees it’s an image manipulation URL because it starts with /img/
  • It sees the path to an image: assets/vacations/italy/trevi-fountain.jpg
  • It will manipulate and output an image based on the parameters. ?w=100&h=100.

The appropriate way to generate these URLs in your templates is by using the Glide Tag.

{{ glide src="/assets/vacations/italy/trevi-fountain.jpg"
         width="100" height="100" }}

The Glide tag can also accept asset IDs for private assets, and even external URLs. It’s quite handy!
Visit the Glide Tag’s docs for more details.

Manipulation Presets

You may define named presets to simplify your templates.

Within site/settings/assets.yaml, you can add a list of presets with the keys as their names, and the values as an array of raw Glide API parameters. For example:

image_manipulation_presets:
  sml:
    w: 200
    h: 200
  tall:
    w: 200
    h: 600

Whenever you upload a new image asset through the control panel, all of that image’s presets will be created automatically.

To pre-generate the presets for existing assets, you can run the CLI command php please assets:generate-presets.

To use presets combine them with a Glide Tag.

{{ glide src="/assets/vacations/italy/trevi-fountain.jpg" preset="sml" }}

Queueing Presets

Presets are generated when you upload the assets. Depending on how many presets you have, and what’s involved in each, this may take a long time, or even cause the request to run out of memory.

You may push the presets into a queue so they can run in the background. Here’s how:

  • Ensure Redis is installed and running on your server.
  • Add QUEUE_DRIVER=redis to your .env file. What’s an .env file?.
  • Run php please queue:listen

You can use whatever drivers Laravel supports for queues. On Laravel Forge, beanstalkd is enabled by default.

Asset Container Drivers

The examples above assume you are storing your assets in folders within your site. However, it is possible to store them in other locations on your server, or even in the cloud using Amazon S3.

Within each container’s configuration file, you may specify the driver and its various options.

Local Filesystem

When a container doesn’t have a driver specified, Statamic will assume it uses the local driver.

title: Local Assets
path: path/to/asset/folder
url: /url/of/asset/folder

The path may be:

  • A path relative to the main filesystem root. (eg. path/to/assets) This can be inside or outside your site’s root folder.
  • An absolute path. (eg. /var/www/example.com/assets)
  • An absolute path with an interpolated environment variable. (eg. "{env‌:BASE_PATH}/assets")

As mentioned above, the url should be the location of the asset folder. If it’s located outside of the webroot, it’s inaccessible so you can just leave it blank. A container without a URL will be considered private.

Amazon S3

To enable S3 assets in a container, you should set up your container configuration file like so:

title: S3 Assets
driver: s3
key:     # Access Key ID
secret:  # Secret Access Key
bucket:  # The bucket name
region:  # The region code (eg. us-west-1)
path:    # A subfolder of the bucket, if you'd like
cache:   # A cache time in seconds. More info below.

The region codes can be tough to remember. Here’s a list of them.

S3 Filesystem Caching

Amazon S3 requires API calls to retrieve information from Amazon. With a lot of files, and a lot of actions, this can very easily become slow.

The filesystem may be cached with Redis to prevent repeated API calls.

  • Ensure your server has Redis installed and running.
  • Set the cache key in your container configuration file to the number of seconds a particular folder’s contents should be cached.

Statamic 2.5 Changes

Statamic 2.5 fundamentally changed how the asset system works, for ease of use and for performance reasons. If you’re coming from an earlier version, here’s what you’ll want to know:

  • You no longer need to add each asset to a YAML file. If the file exists in the folder, it simply exists. No syncing necessary.
  • The containers have moved from site/storage/assets/[id]/container.yaml to site/content/assets/[id].yaml.
  • Instead of a separate folder.yaml file to track assets in each subfolder, all additional asset data is held in the container file.
  • You now reference assets in your content with their URLs instead of IDs.
  • Asset IDs technically still exist, but now they are just [container id]::[path to file]. Not a crazy UUID.
  • Asset IDs are used in your content for private containers.
  • All of the required changes are handled during the upgrade process. It’s all automatic.

Last Updated February 22, 2017

Table of Contents
  1. Overview
  2. Containers
  3. Managing Assets
  4. Control Panel
    1. Asset Manager
    2. Asset Fieldtype
  5. Templating
  6. Additional asset data
  7. Private Assets
  8. Image Manipulation
    1. Manipulation Presets
      1. Queueing Presets
  9. Asset Container Drivers
    1. Local Filesystem
    2. Amazon S3
      1. S3 Filesystem Caching
  10. Statamic 2.5 Changes