How do Filesystems work?
A flat file CMS would be nothing without flexible control of files. Learn how to configure and leverage Statamic's filesystems.
Yes. Plural. Statamic has several self-contained filesystems powered by Flysystem. By breaking the application structure into siloed locations, each with its own filesystem, we gain the ability to physically put these files in more locations (Amazon S3 for example) than a single web directory. What you do with that ability is up to you. We feel compelled to tell you there’s nothing wrong with defaults. Don’t succumb to complex configuration simply to step up your Tinder game. It probably won’t impress anybody.
Statamic has 5 core filesystems, each with its own ‘root’:
- Asset Containers
We make some out of the box assumptions about your configuration, all of which can be changed.
Here’s a simplified version of what you see in a freshly unzipped Statamic installation:
/ / |-- assets/ |-- local/ |-- site/ | |-- content/ | |-- storage/ | |-- users/ | `-- themes/ |-- statamic/ `-- index.php
Content and Storage
The content and storage filesystems’ roots will be
A common use case for moving something outside of the default webroot is to have a publicly-accessible repo for just content, keeping the rest of the site private. In fact, these docs do that very thing.
The users filesystem’s root will be
Since you may potentially have many users, or wish the keep your celebrity gossip blogger’s identity secret, you might want to keep them separate from your repo.
The themes filesystem’s root will be
The themes folder needs to be publicly accessible, so we’ve added a
url value here too. This will let Statamic know
how to access that folder from the browser. We’ll use that for links to stylesheets, etc.
Each asset container gets its own filesystem. Now you can put them on S3, for example.
The sample asset container included with Statamic will have its filesystem root set to
The server filesystem is used for finding any files that aren’t moveable, those that need to always be on your server for the application to function. We’ll use this filesystem for accessing settings, application files, and whatever else we didn’t feel like typing out here because it doesn’t and shouldn’t matter to you.
The server filesystem’s root will always be the folder above your
Moving things around
Now that you know what the filesystems are and that you can move them around, you’ll want to know how.
The defaults settings are stored in your
site/settings/system.yaml file like so:
filesystems: content: driver: local root: site/content storage: driver: local root: site/storage users: driver: local root: site/users themes: driver: local root: site/themes url: /site/themes
If you don’t see this in your
system.yaml just copy these settings in or use the Control Panel.
To relocate a filesystem, simply change the
root variable to one of the following:
- A path relative to the main filesystem root. (eg.
- An absolute path. (eg.
- An absolute path with an interpolated environment variable. (eg.
* Asset containers can be modified in their respective
container.yaml file or CP pages.
To manipulate each filesystem, we’ll use the
Statamic\API\Folder class and specify a
disk depending on which one we want to access. If a disk isn’t specified, the main filesystem will be used.
When passing paths into methods, you’ll want to treat them as relative to the filesystem you’re using.
use Statamic\API\File; $home = File::disk('content')->get('pages/index.md'); $document = File::disk('storage')->get('documents/important.pdf'); $admin = File::disk('users')->get('admin.yaml'); $css = File::disk('themes')->get('redwood/css/style.css'); $system = File::get('site/settings/system.yaml');