Methods to create sysFile and sysFileReference entries.


 └─ \TYPO3\CMS\Extbase\Domain\Model\FileReference
        ... getOriginalResource()
                └─ \TYPO3\CMS\Core\Resource\FileReference
                    ... getOriginalFile()
                            └─ \TYPO3\CMS\Core\Resource\File

Overview of Methods

\nn\t3::Fal()->attach($model, $field, $itemData = NULL);

Convert a file to a FileReference object, and attach it Attach it to the Property or ObjectStorage of a model. See also: \nn\t3::Fal()->setInModel( $member, 'falslideshow', $imagesToSet ); with the array of multiple images can be attached to an ObjectStorage.

\nn\t3::Fal()->attach( $model, $fieldName, $filePath );
\nn\t3::Fal()->attach( $model, 'image', 'fileadmin/user_uploads/image.jpg' );
\nn\t3::Fal()->attach( $model, 'image', ['publicUrl'=>'fileadmin/user_uploads/image.jpg'] );
\nn\t3::Fal()->attach( $model, 'image', ['publicUrl'=>'fileadmin/user_uploads/image.jpg', 'title'=>'Title...'] );
@return \TYPO3\CMS\Extbase\Domain\Model\FileReference

\nn\t3::Fal()->clearCache($filenameOrSysFile = '');

Deletes the cache for the image sizes of a FAL including the converted images. If e.g. the f:image-ViewHelper is used, all calculated image sizes will be are stored in the table sys_file_processedfile. Ächanges the original image, an image from the cache may still be accessed.

\nn\t3::Fal()->clearCache( 'fileadmin/file.jpg' );
\nn\t3::Fal()->clearCache( $fileReference );
\nn\t3::Fal()->clearCache( $falFile );
@param $filenameOrSysFile FAL or path (string) to the file.
@return void

\nn\t3::Fal()->createFalFile($storageConfig, $srcFile, $keepSrcFile = false, $forceCreateNew = false);

Creates a File (FAL) Object (sys_file)

nnt3::Fal()->createFalFile( $storageConfig, $srcFile, $keepSrcFile, $forceCreateNew );

@param string $storageConfig Path/folder where FAL file should be stored (e.g. 'fileadmin/projectdata/').
@param string $srcFile Source file to be converted to FAL (e.g. 'uploads/tx_nnfesubmit/example.jpg').

Can also be URL to YouTube/Vimeo video (e.g. https://www.youtube.com/watch?v=7Bb5jXhwnRY) | @param boolean $keepSrcFile Copy source file only, not move it? | @param boolean $forceCreateNew Should new file always be created? If not, it returns existing File object if necessary

@return \Nng\Nnhelpers\Domain\Model\File|\TYPO3\CMS\Core\Resource\File|boolean

\nn\t3::Fal()->createForModel($model, $field, $itemData = NULL);

Convert a file to a FileReference object and für attach() to an existing Prepare model and field/property. The FileReference will not be attached to the model automatically. automatically attached to the model. To set the FAL directly in the model, you can use the helper | \nn\t3::Fal()->attach( $model, $field, $itemData ) can be used.

\nn\t3::Fal()->createForModel( $model, $fieldName, $filePath );
\nn\t3::Fal()->createForModel( $model, 'image', 'fileadmin/user_uploads/image.jpg' );
\nn\t3::Fal()->createForModel( $model, 'image', ['publicUrl'=>'fileadmin/user_uploads/image.jpg'] );
\nn\t3::Fal()->createForModel( $model, 'image', ['publicUrl'=>'fileadmin/user_uploads/image.jpg', 'title'=>'Title...'] );
@return \TYPO3\CMS\Extbase\Domain\Model\FileReference

\nn\t3::Fal()->createSysFile($file, $autoCreateStorage = true);

Creates new entry in sys_file Searches all sys_file_storage entries to see if the path to the $file already exists as storage. If not, a new storage will be created.

\nn\t3::Fal()->createSysFile( 'fileadmin/image.jpg' );
\nn\t3::Fal()->createSysFile( '/var/www/mysite/fileadmin/image.jpg' );
@return false|\TYPO3\CMS\Core\Resource\File

\nn\t3::Fal()->deleteProcessedImages($sysFile = '');

Deletes all physical thumbnail files that have been generated for an image incl. the records in the sys_file_processedfile table.

The original image, passed as argument $path üis not deleted in the process. The whole thing forces the regeneration of thumbnails for an image if, for example, the source image has changed. source image has changed but the filename has remained the same.

Another use case: clean up files on the server, e.g. because sensitive, personal data has been deleted. Data should be deleted incl. all generated thumbnails.

\nn\t3::Fal()->deleteProcessedImages( 'fileadmin/path/sample.jpg' );
\nn\t3::Fal()->deleteProcessedImages( $sysFileReference );
\nn\t3::Fal()->deleteProcessedImages( $sysFile );
@return mixed

\nn\t3::Fal()->deleteSysFile($uidOrObject = NULL);

Deletes a SysFile (record from table sys_file) and all associated SysFileReferences. A radical way to take an image completely out of Typo3's indexing.

The physical file is not deleted from the server! See \nn\t3::File()->unlink() to delete the physical file. See \nn\t3::Fal()->detach( $model, $field ); for löling from a model.

\nn\t3::Fal()->deleteSysFile( 1201 );
\nn\t3::Fal()->deleteSysFile( 'fileadmin/path/to/image.jpg' );
\nn\t3::Fal()->deleteSysFile( \TYPO3\CMS\Core\Resource\File );
\nn\t3::Fal()->deleteSysFile( \TYPO3\CMS\Core\Resource\FileReference );
@param $uidOrObject
@return integer

\nn\t3::Fal()->deleteSysFileReference($uidOrFileReference = NULL);

Lödeletes a SysFileReference. See also \nn\t3::Fal()->detach( $model, $field ); to delete from a model.

\nn\t3::Fal()->deleteSysFileReference( 112 );
\nn\t3::Fal()->deleteSysFileReference( \TYPO3\CMS\Extbase\Domain\Model\FileReference );
@param $uidOrFileReference
@return mixed

\nn\t3::Fal()->detach($model, $field, $obj = NULL);

Deletes an ObjectStorage in a model or removes an single Object from the Model or an ObjectStorage. In the example, image can be an ObjectStorage or a single FileReference:

\nn\t3::Fal()->detach( $model, 'image' );
\nn\t3::Fal()->detach( $model, 'image', $singleObjToRemove );
@return void

\nn\t3::Fal()->fileReferenceExists($sysFile = NULL, $params = []);

Checks if a SysFileReference to the same SysFile already exists for a record

\nn\t3::Fal()->fileReferenceExists( $sysFile, ['uid_foreign'=>123, 'tablenames'=>'tt_content', 'field'=>'media'] );
@param $sysFile
@param array $params => uid_foreign, tablenames, fieldname.
@return FileReference|false


\nn\t3::Fal()->fromFile($params = []);

Creates a FileRefence object (table: sys_file_reference) and associates it with a record. Example: Uploaded JPG should be attached as FAL to tt_news record


key description


path to source file (can also be http link to YouTube video)


Path to destination folder (optional if file is to be moved/copied)


Target table to which FileReference should be assigned (e.g. tx_myext_domain_model_entry)










Target table to which the FileReference should be assigned (e.g. tx_myext_domain_model_entry)


(int) sorting


Column name of the target table to which the FileReference should be assigned (e.g., image)


(int) uid of the record in the target table (tx_myext_domain_model_entry.uid)


(int) pid of the record in the destination table


cruser_id of the record in the target table


src file do not move but copy (default: true)


Force new file in destination folder (otherwise checks if file already exists) default: false


Make sure that same FileReference is linked only 1x per record (default: true)


$fal = \nn\t3::Fal()->fromFile([
    'src' => 'fileadmin/test/image.jpg',
    'dest' => 'fileadmin/test/fal/',
    'pid' => 132,
    'uid' => 5052,
    'table' => 'tx_myext_domain_model_entry',
    'field' => 'fallistimage'
@return \TYPO3\CMS\Extbase\Domain\Model\FileReference



Gets a File (FAL) object (sys_file)

\nn\t3::Fal()->getFalFile( 'fileadmin/image.jpg' );
@param string $srcFile
@return \TYPO3\CMS\Core\Resource\File|boolean

\nn\t3::Fal()->getFileObjectFromCombinedIdentifier($file = '');

Gets a SysFile from the CombinedIdentifier notation ('1:/uploads/example.txt'). If file does not exist FALSE will be returned.

\nn\t3::Fal()->getFileObjectFromCombinedIdentifier( '1:/uploads/example.txt' );
@param string $file Combined Identifier ('1:/uploads/example.txt')
@return file|boolean


Get the URL to a FileReference or FalFile. Alias to \nn\t3::File()->getPublicUrl().

\nn\t3::Fal()->getFilePath( $fileReference ); // results in e.g. 'fileadmin/pictures/01.jpg'
@param \TYPO3\CMS\Extbase\Domain\Model\FileReference|\TYPO3\CMS\Core\Resource\FileReference $falReference
@return string

\nn\t3::Fal()->getFileReferenceByUid($uid = NULL);

Gets a SysFileReference based on the uid. Alias to \nn\t3::Convert( $uid )->toFileReference();

\nn\t3::Fal()->getFileReferenceByUid( 123 );
@param $uid
@return \TYPO3\CMS\Extbase\Domain\Model\FileReference


\nn\t3::Fal()->getImage($src = NULL);

. Gets/converts to a TYPO3CMSCoreResourceFileReference Object (sys_file_reference). "Smart" variant to \TYPO3\CMS\Extbase\Service\ImageService->getImage()

\nn\t3::Fal()->getImage( 1 );
\nn\t3::Fal()->getImage( 'path/to/image.jpg' );
\nn\t3::Fal()->getImage( $fileReference );
@param string|\TYPO3\CMS\Extbase\Domain\Model\FileReference $src
@return \TYPO3\CMS\Core\Resource\FileReference|boolean

\nn\t3::Fal()->process($fileObj = '', $processing = []);

Calculates an image üover maxWidth, maxHeight, cropVariant etc. Returns URI to image as string. Helpful when calculating thumbnails in the backend. Alias to \nn\t3::File()->process()

\nn\t3::File()->process( 'fileadmin/images/portrait.jpg', ['maxWidth'=>200] );
\nn\t3::File()->process( '1:/images/portrait.jpg', ['maxWidth'=>200] );
\nn\t3::File()->process( $sysFile, ['maxWidth'=>200] );
\nn\t3::File()->process( $sysFileReference, ['maxWidth'=>200, 'cropVariant'=>'square'] );
@return string

\nn\t3::Fal()->setInModel($model, $fieldName = '', $imagesToAdd = []);

Replaces a FileReference or ObjectStorage in a model with images. Typical use case: A FAL image should be changed via an upload form in the frontend. in the frontend.

For each image, it is checked if a FileReference already exists in the model. Existing FileReferences are not overwritten, otherwise captions or cropping annotations might be used. Captions or cropping instructions would be lost!

Attention! The model will be persisted automatically!

$newModel = new \My\Extension\Domain\Model\Example();
\nn\t3::Fal()->setInModel( $newModel, 'falslideshow', 'path/to/file.jpg' );
echo $newModel->getUid(); // Model has been persisted!

Example with a simple FileReference in the Model:

$imageToSet = 'fileadmin/images/portrait.jpg';
\nn\t3::Fal()->setInModel( $member, 'falprofileimage', $imageToSet );

\nn\t3::Fal()->setInModel( $member, 'falprofileimage', ['publicUrl'=>'01.jpg', 'title'=>'title', 'description'=>'...'] );

Example with an ObjectStorage in the model:

$imagesToSet = ['fileadmin/images/01.jpg', 'fileadmin/images/02.jpg', ...];
\nn\t3::Fal()->setInModel( $member, 'falslideshow', $imagesToSet );

\nn\t3::Fal()->setInModel( $member, 'falslideshow', [['publicUrl'=>'01.jpg'], ['publicUrl'=>'02.jpg']] );
\nn\t3::Fal()->setInModel( $member, 'falvideos', [['publicUrl'=>'https://youtube.com/?watch=zagd61231'], ...] );

Example with videos:

$videosToSet = ['https://www.youtube.com/watch?v=GwlU_wsT20Q', ...];
\nn\t3::Fal()->setInModel( $member, 'videos', $videosToSet );
@param mixed $model The model to be changed.
@param string $fieldName Property (field name) of the ObjectStorage or FileReference.
@param mixed $imagesToAdd String / array of images
@return mixed

\nn\t3::Fal()->toArray($fileReference = NULL);

Convert a FileReference to an array. Contains publicUrl, title, alternative, crop etc of the FileReference. Alias to \nn\t3::Obj()->toArray( $fileReference );

\nn\t3::Fal()->toArray( $fileReference ); // yields ['publicUrl'=>'fileadmin/...', 'title'=>'...']
@param \TYPO3\CMS\Extbase\Domain\Model\FileReference $falReference
@return array

\nn\t3::Fal()->updateMetaData($filenameOrSysFile = '', $data = []);

Update the data in sys_file_metadata and sys_file

\nn\t3::Fal()->updateMetaData( 'fileadmin/file.jpg' );
\nn\t3::Fal()->updateMetaData( $fileReference );
\nn\t3::Fal()->updateMetaData( $falFile );
@param $filenameOrSysFile FAL or path (string) to the file.
@param $data Array of data to be updated.

If empty, image data will be read automatically | @return void