Attention
TYPO3 v10 has reached end-of-life as of April 30th 2023 and is no longer being maintained. Use the version switcher on the top left of this page to select documentation for a supported version of TYPO3.
Need more time before upgrading? You can purchase Extended Long Term Support (ELTS) for TYPO3 v10 here: TYPO3 ELTS.
Working With Files, Folders and File References¶
This chapter provides some examples about interacting with File, Folder and FileReference objects.
Getting a File¶
A file can be retrieved using its uid:
$resourceFactory = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Resource\ResourceFactory::class);
$file = $resourceFactory->getFileObject(4);
or its combined identifier:
$resourceFactory = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Resource\ResourceFactory::class);
$file = $resourceFactory->getFileObjectFromCombinedIdentifier('1:/foo.txt');
The syntax of argument 1 for getFileObjectFromCombinedIdentifier is
[[storage uid]:]<file identifier>
The return value is
File|ProcessedFile|null
The storage uid is optional. If it is not specified, the default storage 0 will be assumed initially.
The default storage is virtual with $uid === 0
in its class \TYPO3\CMS\Core\Resource\ResourceStorage
. In this case the local filesystem is checked for the given file.
The file identifier is the local path and filename relative to the TYPO3 fileadmin/
folder.
Example: /templates/stylesheets/fonts.css
, if the file /absolute/path/to/fileadmin/templates/stylesheets/fonts.css
exists on the file system.
The file can be accessed from the default storage, if it exists under the given local path in fileadmin/
.
In case the file is not found, a search for another storage best fitting to this local path will be started. Afterwards the file identifier is adapted accordingly inside of TYPO3 to match the new storage's base path.
Copying a File¶
$storageUid = 17;
$someFileIdentifier = 'templates/images/banner.jpg';
$someFolderIdentifier = 'website/images/';
$resourceFactory = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Resource\ResourceFactory::class);
$storage = $resourceFactory->getStorageObject($storageUid);
// $file returns a TYPO3\CMS\Core\Resource\File object
$file = $storage->getFile($someFileIdentifier);
// $folder returns a TYPO3\CMS\Core\Resource\Folder object
$folder = $storage->getFolder($someFolderIdentifier);
// returns the TYPO3\CMS\Core\Resource\File object of the new, copied file
$copiedFile = $file->copyTo($folder);
Adding a File¶
This example adds a new file in the root folder of the default Storage:
$resourceFactory = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Resource\ResourceFactory::class);
$storage = $resourceFactory->getDefaultStorage();
$newFile = $storage->addFile(
'/tmp/temporary_file_name.ext',
$storage->getRootLevelFolder(),
'final_file_name.ext'
);
The default storage uses fileadmin
unless this was configured
differently, as explained in Storages and Drivers.
So, for this example, the resulting file path would typically be
<document-root>/fileadmin/final_file_name.ext
To store the file in a sub folder use $storage->getFolder()
:
$newFile = $storage->addFile(
'/tmp/temporary_file_name.ext',
$storage->getFolder('some/nested/folder'),
'final_file_name.ext'
);
In this example, the file path would likely be
<document-root>/fileadmin/some/nested/folder/final_file_name.ext
Creating a File Reference¶
In the Backend Context¶
In the backend or command-line context, it is possible to create
file references using the DataHandler
processes (\TYPO3\CMS\Core\DataHandling\DataHandler
).
Assuming you have the "uid" of both the File and whatever other item you want to create a relation to, the following code will create the "sys_file_reference" entry and the relation to the other item (in this case a "tt_content" record):
$resourceFactory = GeneralUtility::makeInstance(ResourceFactory::class);
$fileObject = $resourceFactory->getFileObject((int)$file);
$contentElement = BackendUtility::getRecord(
'tt_content',
(int)$element
);
// Assemble DataHandler data
$newId = 'NEW1234';
$data = [];
$data['sys_file_reference'][$newId] = [
'table_local' => 'sys_file',
'uid_local' => $fileObject->getUid(),
'tablenames' => 'tt_content',
'uid_foreign' => $contentElement['uid'],
'fieldname' => 'assets',
'pid' => $contentElement['pid']
];
$data['tt_content'][$contentElement['uid']] = [
'assets' => $newId
];
// Get an instance of the DataHandler and process the data
/** @var DataHandler $dataHandler */
$dataHandler = GeneralUtility::makeInstance(DataHandler::class);
$dataHandler->start($data, []);
$dataHandler->process_datamap();
// Error or success reporting
if (count($dataHandler->errorLog) === 0) {
// Handle success
} else {
// Handle errors
}
The above example comes from the "examples" extension (reference: https://github.com/TYPO3-Documentation/t3docs-examples/blob/master/Classes/Controller/ModuleController.php).
Here, the 'fieldname'
'assets'
is used instead of
image
. Content elements of ctype 'textmedia' use the field 'assets'.
For another table than "tt_content", you need to define the "pid" explicitly when creating the relation:
$data['tt_address'][$address['uid']] = [
'pid' => $address['pid'],
'image' => 'NEW1234' // changed automatically
];
In the Frontend Context¶
In a frontend context, the \TYPO3\CMS\Core\DataHandling\DataHandler
class cannot be used and there is no specific API to create a File Reference.
You are on your own.
The simplest solution is to create a database entry into table "sys_file_reference" by using the database connection class provided by TYPO3 CMS.
A cleaner solution using Extbase requires far more work. An example can be found here: https://github.com/helhum/upload_example
Getting Referenced Files¶
This snippet shows how to retrieve FAL items that have been attached to some other element, in this case the "media" field of the "pages" table:
$fileRepository = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Resource\FileRepository::class);
$fileObjects = $fileRepository->findByRelation('pages', 'media', $uid);
where $uid
is the id of some page. The return value is an array
of \TYPO3\CMS\Core\Resource\FileReference
objects.
Listing Files in a Folder¶
These would be the shortest steps to get the list of files in a given folder: get the storage, get a folder object for some path in that storage (path relative to storage root), finally retrieve the files:
$resourceFactory = \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance(\TYPO3\CMS\Core\Resource\ResourceFactory::class);
$defaultStorage = $resourceFactory->getDefaultStorage();
$folder = $defaultStorage->getFolder('/some/path/in/storage/');
$files = $defaultStorage->getFilesInFolder($folder);
Dumping a file via eID Script¶
TYPO3 registers an eID
script that allows dumping / downloading / referencing files via their FAL ids. Non-public storages use this script
to make their files available to view or download. File retrieval is done via PHP and delivered through the eID
script.
An example URL looks like this: index.php?eID=dumpFile&t=f&f=1230&token=135b17c52f5e718b7cc94e44186eb432e0cc6d2f
.
Following URI-Parameters are available:
t
(Type): Can be one off
(sys_file
),r
(sys_file_reference
) orp
(sys_file_processedfile
)f
(File): UID of tablesys_file
r
(Reference): UID of tablesys_file_reference
p
(Processed): UID of tablesys_file_processedfile
s
(Size): Size (width and height) of the filecv
(CropVariant): In case ofsys_file_reference
, you can assign a cropping variant
You have to choose one of these parameters: f
, r
or p
. It is not possible
to combine them in one request.
The Parameter s
has following syntax: width:height:minW:minH:maxW:maxH
. You
can leave this parameter empty to load the file in its original size. Parameter width
and height
can feature the trailing c
or m
indicator, as known from TypoScript.
The PHP class responsible for handling the file dumping is the FileDumpController
, which you
may also use in your code.
See the following example on how to create a URI using the FileDumpController
for
a sys_file
record with a fixed image size:
$queryParameterArray = ['eID' => 'dumpFile', 't' => 'f'];
$queryParameterArray['f'] = $resourceObject->getUid();
$queryParameterArray['s'] = '320c:280c';
$queryParameterArray['token'] = GeneralUtility::hmac(implode('|', $queryParameterArray), 'resourceStorageDumpFile');
$publicUrl = GeneralUtility::locationHeaderUrl(PathUtility::getAbsoluteWebPath(Environment::getPublicPath() . '/index.php'));
$publicUrl .= '?' . http_build_query($queryParameterArray, '', '&', PHP_QUERY_RFC3986);
In this example crop variant default
and an image size of 320:280 will be
applied to a sys_file_reference record:
$queryParameterArray = ['eID' => 'dumpFile', 't' => 'r'];
$queryParameterArray['f'] = $resourceObject->getUid();
$queryParameterArray['s'] = '320c:280c:320:280:320:280';
$queryParameterArray['cv'] = 'default';
$queryParameterArray['token'] = GeneralUtility::hmac(implode('|', $queryParameterArray), 'resourceStorageDumpFile');
$publicUrl = GeneralUtility::locationHeaderUrl(PathUtility::getAbsoluteWebPath(Environment::getPublicPath() . '/index.php'));
$publicUrl .= '?' . http_build_query($queryParameterArray, '', '&', PHP_QUERY_RFC3986);
This example shows how to create a URI to load an image of
sys_file_processedfile
:
$queryParameterArray = ['eID' => 'dumpFile', 't' => 'p'];
$queryParameterArray['p'] = $resourceObject->getUid();
$queryParameterArray['token'] = GeneralUtility::hmac(implode('|', $queryParameterArray), 'resourceStorageDumpFile');
$publicUrl = GeneralUtility::locationHeaderUrl(PathUtility::getAbsoluteWebPath(Environment::getPublicPath() . '/index.php'));
$publicUrl .= '?' . http_build_query($queryParameterArray, '', '&', PHP_QUERY_RFC3986);
The following restrictions apply:
You can't assign any size parameter to processed files, as they are already resized.
You can't apply CropVariants to
sys_file
andsys_file_processedfile
records, only tosys_file_reference