Assets

Overview

Assets live in directories on your local server, in an Amazon S3 bucket, or other cloud storage services. Each defined location is called a container..

Statamic scans the files in each container and caches meta information (like width and height for images) on them. This cache is used to speed up interactions and response times when working with them on the frontend of your site.

Asset Browser

You can explore these files in the Control Panel's asset browser. You can file, sort, search, move, rename, preview, and — if working with images — even set focal crop points to make dynamically resized images look their best.

Asset Fields

Asset fields are configured like a blueprint and attached to the container. Whenever you edit an asset in the Control Panel, you'll see the fields from the configured blueprint.

This data is stored in the asset's meta data file.

Metadata

Asset metadata is stored in YAML files inside a hidden .meta subdirectory inside each container. For example, images/tree.jpg gets an images/.meta/tree.jpg.yaml cache file.

These files contain cached data, including but not limited to: image dimensions, file size, last modification dates, and so on.

These cache files can also contain user created data. The fields are defined by the asset container's blueprint. Typically these are alt text, focal points, descriptions, and so on, but they could be anything you want at all.

size: 9151
last_modified: 1558533973
width: 216
height: 104
data:
  alt: 'A tree with a tire swing'
  focus: 54-54-1

Containers

Each container has its own settings, configurable permissions, and blueprint. One container might be a local filesystem with upload, download, rename, and move permissions enabled, and another could be a read-only remote S3 bucket or stock image service.

Containers can be created through the Control Panel and are defined as YAML files located in content/assets. Each container's filename becomes its handle.

# content/assets/assets.yaml
title: 'Assets'
disk: 'assets'

Each container implements a "disk", also known as a Laravel Filesystem. This native Laravel feature groups a driver, URL, location, and visibility together. Statamic includes a local disk on fresh installs. You can modify or delete it, but many sites can simply use it as is.

'disks' => [
    'assets' => [
        'driver' => 'local',
        'root' => public_path('assets'),
        'url' => '/assets',
        'visibility' => 'public', // (more info about visibility below)
    ],
]

Filesystems are defined in config/filesystems.php They can point to the local filesystem, S3, or any Flysystem adapter.

Private Containers

Sometimes it’s handy to store assets that shouldn’t be publicly visible through a direct URL or browser.

Private containers should be located above webroot. If you leave the disk within the webroot, the files will still be accessible directly outside of Statamic if you know the file path.

/
   app/
   content/
   config/
   public/
      not-in-here/ 
      index.php
   put-it-out-here/ 
   resources/
   vendor/

Make sure to also set the visibility to private.

Container Visibility

Your filesystem's disk can have a visibility which is an abstraction of file permissions. You can set it to public or private,
which essentially controls whether they're accessible or not.

Be sure to set 'visibility' => 'public', if you want to be able to see, interact with, and manipulate files in your container.

Blueprints

The default container Blueprint contains a single "alt text" field — just useful and simple enough to get you started.

You can customize the fields on the blueprint by visiting the container in the Control Panel and choosing "Edit Blueprint" in the options dropdown.

If you want to edit the blueprint file directly, you can do so in resources/blueprints/assets/{handle}.yaml.

Ordering

Default Sort Order in Listings

You can choose which field and direction to sort the list of assets in the Control Panel by setting the sort_by and sort_dir variables in your container.yaml. By default the file name will be used.

Drivers

Statamic uses Flysystem and includes the core local driver. S3, SFTP, and other drivers can be installed with composer.

Flysystem is not limited to these three, however. There are adapters for many other storage systems. You can create a custom driver if you want to use one of these additional adapters in your Laravel application.

Frontend Templating

There are two main methods for working with Asset data on the frontend. The Assets Fieldtype, and the Assets Tag.

Assets Fieldtype

The Assets Fieldtype can be used in your content Blueprints to attach assets to your entries, taxonomy terms, globals, or user accounts. It can be used to create image galleries, video players, zip downloads, or anything else you can think of.

All of the data stored on your Assets will be available on the frontend without having to create any kind of duplication.

Example

If you had a slideshow field with a whole bunch of images selected, you can render them by looping through them.

<div class="slideshow">
    {{ slideshow }}
        <img src="{{ url }}" alt="{{ alt }}">
    {{ /slideshow }}
</div>

Learn more about the Assets Fieldtype.

Assets Tag

If you ever find yourself needing to loop over all of the assets in a container (or folder inside a container) instead of selecting them manually with the Assets Fieldtype, this is the way.

Example

{{ assets container="photoshoots" limit="10" sort="rating" }}
    <img src="{{ url }}" alt="{{ alt }}" />
{{ /assets }}

Learn more about the Assets Tag and what you can do with it.

Manipulating Images

Statamic uses the Glide library to dynamically resize, crop, and manipulate images. It's really easy to use and has its own tag.

{{ glide:image width="120" height="500" filter="sepia" }}