Who this is for. Developers and content modellers working with uploads: planning a media library, an import or a migration. After this page you know what the file manager stores, what replacing an asset changes, and why an upload became an image or a file.

This unit covers the storage side of media. Everything a template does with an image (resizing, converting, picture tags) is in Images end to end.

Folders, filenames, files and revisions

Four objects, from the outside in:

  • A folder is a node in a tree, with a parent and children, and its path is built from the folders above it. Deleting a folder marks it hidden rather than removing it.
  • A filename is an entry in a folder: a name, a type (image or file), an optional expiry date, comments, and exactly one file or image behind it. A name is unique within its folder. The folder's path plus the name is the filename's address, the path that pages and links use.
  • A file or an image is the content behind a filename. It is versioned with the same revisions mechanism as pages: an active revision and a history. Each also carries tags and categories.
  • Each revision holds one version of the bytes, kept in a virtual file. An image revision also records the image's width and height; a file revision has no dimensions.

Folders, filenames, files and images belong to the whole account, not to one site. On an account with several sites, every site shares one file tree.

Why a filename is separate from its file

The filename is the address and the file is the content. Replacing an asset (an upload with the update duplicate strategy) adds a new revision behind the same filename and makes it the active one. The filename's path does not move, so every page, layout area and external link that uses the address keeps working and now gets the new bytes. Nothing has to rewrite links, because the address never changed.

The address is also public: anyone who has a filename's path can download the file, and the file manager has no private storage. What that means for member sites is on File access, sharing and expiry.

Images and files

An image has dimensions and can be resized and converted on the way to the page. A file is delivered as it was uploaded. What you can do with an image is in Images end to end.

Which of the two an upload becomes is decided by its content, not by the field, layout area or folder it came through. On upload the platform recognises five image formats: GIF, JPEG, PNG, WebP and SVG. An upload in one of them becomes an image; anything else becomes a file. A real photograph in another format (TIFF, HEIC, BMP, a camera's raw format) is therefore stored as a file and has no transformation chain. Convert such images to a supported format before uploading them.

The upload API also accepts a type parameter. When it disagrees with the content, the upload is refused with HTTP 400 ("Wrong file type; expected image but got file", or the reverse) rather than stored as the wrong kind. An image never turns into a file because it went through the wrong field.

Tags and categories on files

Files and images always have tags and categories. Two settings of the Files module, useTags and useCategories, decide only whether the file manager shows authors the tag and category pickers; the relations exist either way.

A large library needs them when folders alone cannot answer the questions people ask of it: every photo of one product, everything cleared for a campaign, every document for one region. A folder gives each file one place; tags and categories let a file belong to several groupings at once, so files can be found by what they are rather than by where they were filed.

The cost of turning them on late is that switching a setting tags nothing. Every file already uploaded stays untagged until someone or something tags it, and anything that selects files by tag sees only the files tagged since. Decide when the library is set up, and if the answer is yes, have imports set tags as they go.

Deleting and expiry

The file manager keeps lists of deleted folders and deleted files, whose lengths are among the File manager settings. An expiry date on a filename goes further: once the date has passed, a daily task deletes the filename and the file or image behind it for good. Use an expiry for an address that should disappear on a date, not for an asset you want to keep but stop advertising. The details are on File access, sharing and expiry.