Database structure
This chapter lists the various tables related to the file abstraction layer (FAL) and highlights some of their important fields.
sys_file
This table is used to store basic information about each file. Some important fields:
storage
- ID of the storage where the file is stored.
type
-
The type of the file represented by an integer defined by an enum
\TYPO3\
value.CMS\ Core\ Resource\ File Type See File types for more details.
identifier
- A string which should uniquely identify a file within its storage. Duplicate identifiers are possible, but will create a confusion. For the local file system driver, the identifier is the path to the file, relative to the storage root (starting with a slash and using a slash as directory delimiter).
name
- The name of the file. For the local file system driver, this will be the current name of the file in the file system.
sha1
- A hash of the file's content. This is used to detect whether a file has changed or not.
metadata
- Foreign side of the sys_file_metadata
relation. Always
0
in the database, but necessary for the TCA of thesys_
table.file
Caution
Changed in version 13.0.1/12.4.11/11.5.35
Modifying the sys_
table using DataHandler is blocked since TYPO3
version 11.5.35, 12.4.11, and 13.0.1. The table
should not be extended and additional fields should be added to
sys_
. See security advisory TYPO3-CORE-SA-2024-006
for more information.
sys_file_metadata
This table is used to store metadata about each file. It has a one-to-one
relationship with table sys_file.
Contrary to the basic information stored in sys_
, the content of the
table sys_
can be translated.
Most fields are really just additional information. The most important one is:
file
- ID of the
sys_
record of the file the metadata is related to.file
The sys_
table is extended by the system extension
filemetadata. In particular, it adds the necessary definitions
to categorize files with system categories.
Also some other helpful metadata attributes are provided (and some of them can be automatically inferred from the file). Most of these attributes are self-explanatory; this list may not reflect the most recent TYPO3 version, so it is recommended to inspect the actual TCA configuration of that table:
caption
color_
space content_
- Refers to when the contents of the file were created (retrievable for images through EXIF metadata)creation_ date content_
modification_ date copyright
creator
creator_
- Name of a tool that was used to create the file (for example for auto-generated files)tool download_
- An alternate name of a file when being downloaded (to protect actual file name security relevance)name duration
- length of audio/video files, or "reading time"height
keywords
language
- file content languagelatitude
location_
city location_
country location_
region longitude
note
pages
- Related pagespublisher
ranking
- Information on prioritizing files (like "star ratings")source
- Where a file was fetched from (for example from libraries, clients, remote storage, ...)status
- indicate whether a file may need metadata update based on differences between locally cached metadata and remote/actual file metadataunit
- measurement unitsvisible
width
sys_file_reference
This table is used to store all references between files and whatever other records they are used in, typically pages and content elements. The most important fields are:
uid_
local - ID of the file.
uid_
foreign - ID of the related record.
tablenames
- Name of the table containing the related record.
fieldname
- Name of the field of the related record where the relation was created.
title
-
When a file is referenced, normally its title is used (for whatever purpose, like displaying a caption for example). However it is possible to define a title in the reference, which will be used instead of the original file's title.
The fields
description
,alternative
anddownloadname
obey the same principle.
sys_file_processedfile
This table is similar to sys_file, but for "temporary" files, like image previews. This table does not have a TCA representation, as it is only written for using direct SQL queries in the source code.
sys_file_collection
Changed in version 12.2
The two fields storage
and folder
are now combined into the
new field folder_
.
FAL offers the possibility to create file collections, which can then be used for various purposes. By default, they can be used with the "File links" content element.
The most important fields are:
type
- The type of the collection. A collection can be based on hand-picked files, a folder or categories.
files
- The list of selected files. The relationship between files and their collection is also stored in sys_file_reference.
folder_
identifier - The field contains the so-called "combined identifier" in the format
storage:
, where "storage" is thefolder uid
of the correspondingsys_
record andfile_ storage folder
the absolute path to the folder. An example for a combined identifier is1:/
.user_ upload category
- The chosen categories, for category-type collections.
sys_file_storage
This table is used to store the storages available in the installation. The most important fields are:
driver
- The type of driver used for the storage.
configuration
- The storage configuration with regards to its driver. This is a FlexForm field and the current options depend on the selected driver.
sys_filemounts
Changed in version 12.0
File mounts are not specifically part of FAL (they existed long before), but their definition is based on storages. Each file mount is related to a specific storage. The most important field is:
identifier
- The identifier in the format
base:
, wherepath base
is the storage ID andpath
the path to the folder, for example1:/
.user_ upload