TYPO3 12.4 API: ExtendedFileUtility

ExtendedFileUtility extends BasicFileUtility

Contains functions for performing file operations like copying, pasting, uploading, moving, deleting etc. through the TCE

See document "TYPO3 Core API" for syntax

This class contains functions primarily used by tce_file.php (TYPO3 Core Engine for file manipulation) Functions include copying, moving, deleting, uploading and so on...

All fileoperations must be within the filemount paths of the user.

Internal

Since TYPO3 v10, this class should not be used anymore outside of TYPO3 Core, and is considered internal, as the FAL API should be used instead.

Constants

UNSAFE_FILENAME_CHARACTER_EXPRESSION = '\x00-\x2C\/\x3A-\x3F\x5B-\x60\x7B-\xBF'

Properties

$actionPerms : array<string|int, mixed>: This array is self-explaining (look in the class below).
$internalUploadMap : array<string|int, mixed>: Will contain map between upload ID and the final filename
$maxNumber : int: This number decides the highest allowed appended number used on a filename before we use naming with unique strings
$uniquePrecision : int: This number decides how many characters out of a unique MD5-hash that is appended to a filename if getUniqueName is asked to find an available filename.
$existingFilesConflictMode : DuplicationBehavior: Defines behaviour when uploading files with names that already exist; possible values are the values of the \TYPO3\CMS\Core\Resource\DuplicationBehavior enumeration
$fileCmdMap : array<string|int, mixed>
$fileFactory : ResourceFactory: The File Factory
$flashMessages : array<string|int, mixed>: Container for FlashMessages so they can be localized

Methods

cleanFileName() : string: Returns a string where any character not matching [.a-zA-Z0-9_-] is substituted by '_' Trailing dots are removed
folderHasFilesInUse() : bool: Checks files in given folder recursively for for existing references.
func_delete() : bool: Deleting files and folders (action=4)
func_edit() : bool: Editing textfiles or folders (action=9)
func_newfile() : string: This creates a new file. (action=8) $cmds['data'] (string): The new file name $cmds['target'] (string): The path where to create it.
func_newfolder() : Folder|false: This creates a new folder. (action=6)
func_rename() : File: Renaming files or folders (action=5)
func_upload() : array<string|int, File>|bool: Upload of files (action=1) when having multiple uploads (HTML5-style), the array $_FILES looks like this: Array( [upload_1] => Array( [name] => Array( [0] => GData - Content-Elements and Media-Gallery.pdf [1] => CMS Expo 2011.txt ) [type] => Array( [0] => application/pdf [1] => text/plain ) [tmp_name] => Array( [0] => /Applications/MAMP/tmp/php/phpNrOB43 [1] => /Applications/MAMP/tmp/php/phpD2HQAK ) [size] => Array( [0] => 373079 [1] => 1291 ) ) ) in HTML you'd need sth like this: <input type="file" name="upload_1[]" multiple="true" />
getExistingFilesConflictMode() : string: Get existingFilesConflictMode
getUniqueName() : string|null: Returns the destination path/filename of a unique filename/foldername in that path.
processData() : mixed: Processing the command array in $this->fileCmdMap
setActionPermissions() : mixed: Sets the file action permissions.
setExistingFilesConflictMode() : mixed: Set existingFilesConflictMode
start() : mixed: Initialization of the class
addFlashMessage() : mixed: Add flash message to message queue
addMessageToFlashMessageQueue() : mixed: Adds a localized FlashMessage to the message queue
func_copy() : File|false: Copying files and folders (action=2)
func_move() : File|false: Moving files and folders (action=3)
getBackendUser() : BackendUserAuthentication
getFileObject() : File|Folder: Gets a File or a Folder object from an identifier [storage]:[fileId]
getIndexer() : Indexer: Gets Indexer
getLanguageService() : LanguageService
replaceFile() : array<string|int, mixed>|bool: Replaces a file on the filesystem and changes the identifier of the persisted file object in sys_file if keepFilename is not checked. If keepFilename is checked, only the file content will be replaced.
sanitizeFolderPath() : bool|string: Cleans $theDir for slashes in the end of the string and returns the new path, if it exists on the server.
transformFileReferenceToRecordReference() : array<string|int, mixed>: Maps results from the fal file reference table on the structure of the normal reference index table.
writeLog() : void

UNSAFE_FILENAME_CHARACTER_EXPRESSION


    public
        string
    UNSAFE_FILENAME_CHARACTER_EXPRESSION
    = '\x00-\x2C\/\x3A-\x3F\x5B-\x60\x7B-\xBF'

$actionPerms

This array is self-explaining (look in the class below).


    public
        array<string|int, mixed>
    $actionPerms
     = [
    // File permissions
    'addFile' => false,
    'readFile' => false,
    'writeFile' => false,
    'copyFile' => false,
    'moveFile' => false,
    'renameFile' => false,
    'deleteFile' => false,
    // Folder permissions
    'addFolder' => false,
    'readFolder' => false,
    'writeFolder' => false,
    'copyFolder' => false,
    'moveFolder' => false,
    'renameFolder' => false,
    'deleteFolder' => false,
    'recursivedeleteFolder' => false,
]

It grants access to the functions. This could be set from outside in order to enabled functions to users. See also the function setActionPermissions() which takes input directly from the user-record

$internalUploadMap

Will contain map between upload ID and the final filename


    public
        array<string|int, mixed>
    $internalUploadMap
     = []

$maxNumber

This number decides the highest allowed appended number used on a filename before we use naming with unique strings


    public
        int
    $maxNumber
     = 99

$uniquePrecision

This number decides how many characters out of a unique MD5-hash that is appended to a filename if getUniqueName is asked to find an available filename.


    public
        int
    $uniquePrecision
     = 6

$existingFilesConflictMode

Defines behaviour when uploading files with names that already exist; possible values are the values of the \TYPO3\CMS\Core\Resource\DuplicationBehavior enumeration


    protected
        DuplicationBehavior
    $existingFilesConflictMode

$fileCmdMap


    protected
        array<string|int, mixed>
    $fileCmdMap

$fileFactory

The File Factory


    protected
        ResourceFactory
    $fileFactory

$flashMessages

Container for FlashMessages so they can be localized


    protected
        array<string|int, mixed>
    $flashMessages
     = []

cleanFileName()

Returns a string where any character not matching [.a-zA-Z0-9_-] is substituted by '_' Trailing dots are removed


    public
                    cleanFileName(string $fileName) : string

Parameters

$fileName : string: Input string, typically the body of a filename

Internal

May be removed without further notice. Method has been marked as deprecated for various versions but is still used in core.

Return values

string —

Output string with any characters not matching [.a-zA-Z0-9_-] is substituted by '_' and trailing dots removed

folderHasFilesInUse()

Checks files in given folder recursively for for existing references.


    public
                    folderHasFilesInUse(Folder $folder) : bool

Creates a flash message if there are references.

Parameters

$folder : Folder

Return values

bool —

TRUE if folder has files in use, FALSE otherwise

func_delete()

Deleting files and folders (action=4)


    public
                    func_delete(array<string|int, mixed> $cmds) : bool

Parameters

$cmds : array<string|int, mixed>: $cmds['data'] is the file/folder to delete

Return values

bool —

Returns TRUE upon success

func_edit()

Editing textfiles or folders (action=9)


    public
                    func_edit(array<string|int, mixed> $cmds) : bool

Parameters

$cmds : array<string|int, mixed>: $cmds['data'] is the new content. $cmds['target'] is the target (file or dir)

Return values

bool —

Returns TRUE on success

func_newfile()

This creates a new file. (action=8) $cmds['data'] (string): The new file name $cmds['target'] (string): The path where to create it.


    public
                    func_newfile(array<string|int, mixed> $cmds) : string

example "2:targetpath/targetfolder/"

Parameters

$cmds : array<string|int, mixed>: Command details as described above

Return values

string —

Returns the new filename upon success

func_newfolder()

This creates a new folder. (action=6)


    public
                    func_newfolder(array<string|int, mixed> $cmds) : Folder|false

$cmds['data'] (string): The new folder name $cmds['target'] (string): The path where to copy to.

example "2:targetpath/targetfolder/"

Parameters

$cmds : array<string|int, mixed>: Command details as described above

Return values

Folder|false —

Returns the new foldername upon success

func_rename()

Renaming files or folders (action=5)


    public
                    func_rename(array<string|int, mixed> $cmds) : File

$cmds['data'] (string): The file/folder to copy

example "4:mypath/tomyfolder/myfile.jpg")
for backwards compatibility: the identifier was the path+filename $cmds['target'] (string): New name of the file/folder

Parameters

$cmds : array<string|int, mixed>: Command details as described above

Return values

File —

Returns the new file upon success

func_upload()

Upload of files (action=1) when having multiple uploads (HTML5-style), the array $_FILES looks like this: Array( [upload_1] => Array( [name] => Array( [0] => GData - Content-Elements and Media-Gallery.pdf [1] => CMS Expo 2011.txt ) [type] => Array( [0] => application/pdf [1] => text/plain ) [tmp_name] => Array( [0] => /Applications/MAMP/tmp/php/phpNrOB43 [1] => /Applications/MAMP/tmp/php/phpD2HQAK ) [size] => Array( [0] => 373079 [1] => 1291 ) ) ) in HTML you'd need sth like this: <input type="file" name="upload_1[]" multiple="true" />


    public
                    func_upload(array<string|int, mixed> $cmds) : array<string|int, File>|bool

Parameters

$cmds : array<string|int, mixed>: $cmds['data'] is the ID-number (points to the global var that holds the filename-ref ($FILES['upload' . $id]['name']) . $cmds['target'] is the target directory, $cmds['charset'] is the the character set of the file name (utf-8 is needed for JS-interaction)

Return values

array<string|int, File>|bool —

Returns an array of new file objects upon success. False otherwise

getExistingFilesConflictMode()

Get existingFilesConflictMode


    public
                    getExistingFilesConflictMode() : string

Return values

string

getUniqueName()

Returns the destination path/filename of a unique filename/foldername in that path.


    public
                    getUniqueName(string $theFile, string $theDest[, bool $dontCheckForUnique = false ]) : string|null

If $theFile exists in $theDest (directory) the file have numbers appended up to $this->maxNumber. Hereafter a unique string will be appended. This function is used by fx. DataHandler when files are attached to records and needs to be uniquely named in the uploads/* folders

Parameters

$theFile : string: The input filename to check
$theDest : string: The directory for which to return a unique filename for $theFile. $theDest MUST be a valid directory. Should be absolute.
$dontCheckForUnique : bool = false: If set the filename is returned with the path prepended without checking whether it already existed!

Internal

May be removed without further notice. Method has been marked as deprecated for various versions but is still used in core.

Return values

string|null —

The destination absolute filepath (not just the name!) of a unique filename/foldername in that path.

processData()

Processing the command array in $this->fileCmdMap


    public
                    processData() : mixed

Return values

mixed —

FALSE, if the file functions were not initialized

setActionPermissions()

Sets the file action permissions.


    public
                    setActionPermissions([array<string|int, mixed> $permissions = [] ]) : mixed

If no argument is given, permissions of the currently logged in backend user are taken into account.

Parameters

$permissions : array<string|int, mixed> = []: File Permissions.

setExistingFilesConflictMode()

Set existingFilesConflictMode


    public
                    setExistingFilesConflictMode(DuplicationBehavior|string $existingFilesConflictMode) : mixed

Parameters

$existingFilesConflictMode : DuplicationBehavior|string: Instance or constant of \TYPO3\CMS\Core\Resource\DuplicationBehavior

start()

Initialization of the class


    public
                    start(array<string|int, mixed> $fileCmds) : mixed

Parameters

$fileCmds : array<string|int, mixed>: Array with the commands to execute. See "TYPO3 Core API" document

addFlashMessage()

Add flash message to message queue


    protected
                    addFlashMessage(FlashMessage $flashMessage) : mixed

Parameters

$flashMessage : FlashMessage

addMessageToFlashMessageQueue()

Adds a localized FlashMessage to the message queue


    protected
                    addMessageToFlashMessageQueue(string $localizationKey[, array<string|int, mixed> $replaceMarkers = [] ][, ContextualFeedbackSeverity $severity = ContextualFeedbackSeverity::ERROR ]) : mixed

Parameters

$localizationKey : string
$replaceMarkers : array<string|int, mixed> = []
$severity : ContextualFeedbackSeverity = ContextualFeedbackSeverity::ERROR

func_copy()

Copying files and folders (action=2)


    protected
                    func_copy(array<string|int, mixed> $cmds) : File|false

$cmds['data'] (string): The file/folder to copy

example "4:mypath/tomyfolder/myfile.jpg")
for backwards compatibility: the identifier was the path+filename $cmds['target'] (string): The path where to copy to.
example "2:targetpath/targetfolder/" $cmds['altName'] (string): Use an alternative name if the target already exists

Parameters

$cmds : array<string|int, mixed>: Command details as described above

Return values

File|false

func_move()

Moving files and folders (action=3)


    protected
                    func_move(array<string|int, mixed> $cmds) : File|false

$cmds['data'] (string): The file/folder to move

example "4:mypath/tomyfolder/myfile.jpg")
for backwards compatibility: the identifier was the path+filename $cmds['target'] (string): The path where to move to.
example "2:targetpath/targetfolder/" $cmds['altName'] (string): Use an alternative name if the target already exists

Parameters

$cmds : array<string|int, mixed>: Command details as described above

Return values

File|false

getBackendUser()


    protected
                    getBackendUser() : BackendUserAuthentication

Return values

BackendUserAuthentication

getFileObject()

Gets a File or a Folder object from an identifier [storage]:[fileId]


    protected
                    getFileObject(string $identifier) : File|Folder

Parameters

$identifier : string

Return values

File|Folder

getIndexer()

Gets Indexer


    protected
                    getIndexer(ResourceStorage $storage) : Indexer

Parameters

$storage : ResourceStorage

Return values

Indexer

getLanguageService()


    protected
                    getLanguageService() : LanguageService

Return values

LanguageService

replaceFile()

Replaces a file on the filesystem and changes the identifier of the persisted file object in sys_file if keepFilename is not checked. If keepFilename is checked, only the file content will be replaced.


    protected
                    replaceFile(array<string|int, mixed> $cmdArr) : array<string|int, mixed>|bool

Parameters

$cmdArr : array<string|int, mixed>

Return values

array<string|int, mixed>|bool

sanitizeFolderPath()

Cleans $theDir for slashes in the end of the string and returns the new path, if it exists on the server.


    protected
                    sanitizeFolderPath(string $theDir) : bool|string

Parameters

$theDir : string: Directory path to check

Return values

bool|string —

Returns the cleaned up directory name if OK, otherwise FALSE.

transformFileReferenceToRecordReference()

Maps results from the fal file reference table on the structure of the normal reference index table.


    protected
                    transformFileReferenceToRecordReference(array<string|int, mixed> $referenceRecord) : array<string|int, mixed>

Parameters

$referenceRecord : array<string|int, mixed>

Return values

array<string|int, mixed>

writeLog()


    protected
                    writeLog(int $action, int $severity, string $message[, array<string|int, mixed> $context = [] ]) : void

Parameters

$action : int: The action number. See the functions in the class for a hint. Eg. edit is '9', upload is '1' ...
$severity : int: The severity: 0 = message, 1 = error, 2 = System Error, 3 = security notice (admin)
$message : string: This is the default, raw error message in english
$context : array<string|int, mixed> = []: Additional information when the log is shown

ExtendedFileUtility extends BasicFileUtility

Table of Contents

Constants

Properties

Methods

Constants

UNSAFE_FILENAME_CHARACTER_EXPRESSION

Properties

$actionPerms

$internalUploadMap

$maxNumber

$uniquePrecision

$existingFilesConflictMode

$fileCmdMap

$fileFactory

$flashMessages

Methods

cleanFileName()

Parameters

Return values

folderHasFilesInUse()

Parameters

Return values

func_delete()

Parameters

Return values

func_edit()

Parameters

Return values

func_newfile()

Parameters

Return values

func_newfolder()

Parameters

Return values

func_rename()

Parameters

Return values

func_upload()

Parameters

Return values

getExistingFilesConflictMode()

Return values

getUniqueName()

Parameters

Tags

Return values

processData()

Tags

Return values

setActionPermissions()

Parameters

setExistingFilesConflictMode()

Parameters

Tags

start()

Parameters

addFlashMessage()

Parameters

addMessageToFlashMessageQueue()

Parameters

Tags

func_copy()

Parameters

Return values

func_move()

Parameters

Return values

getBackendUser()

Return values

getFileObject()

Parameters

Tags

Return values

getIndexer()

Parameters

Return values

getLanguageService()

Return values

replaceFile()