File

class \TYPO3\CMS\Core\Resource\File

Extends
AbstractFile
Implements
PublicResourceInterface, SystemResourceInterface, ProcessableFileInterface

File representation in the file abstraction layer.

Table of Contents

Interfaces

PublicResourceInterface
This interface is public API and can be referenced in third party code or throughout the TYPO3 core.
SystemResourceInterface
This interface is public API and can be referenced in third party code or throughout the TYPO3 core.
ProcessableFileInterface
Resources that can be processed with TYPO3's imaging pipeline - a FAL File, a FAL FileReference, or a resource outside the File Abstraction Layer (for example a system resource shipped with a package). FileReference does not implement SystemResourceInterface, so this cannot extend it the way ProcessedResourceInterface does - consumers that need SystemResourceInterface-level members (getImageDimension() and friends) narrow with an instanceof check first, same as for File-specific members.

Properties

$deleted  : bool
If set to true, this file is regarded as being deleted.
$identifier  : string
$name  : string
The file name of this file
$properties  : array<non-empty-string, mixed>
Various file properties
$storage  : ResourceStorage|null
The storage this file is located in
$updatedProperties  : array
Contains the names of all properties that have been update since the instantiation of this object

Methods

__construct()  : mixed
Constructor for a file object. Should normally not be used directly, use the corresponding factory methods instead.
__toString()  : string
_getPropertyRaw()  : mixed
calculateChecksum()  : string
Creates a MD5 hash checksum based on the combined identifier of the file, the files' mimetype and the systems' encryption key.
checkActionPermission()  : bool
Check if a file operation (= action) is allowed for this file
copyTo()  : self
Copies this file into a target folder
delete()  : bool
Deletes this file from its storage. This also means that this object becomes useless.
exists()  : bool
Checks if this file exists. This should normally always return TRUE; it might only return FALSE when this object has been created from an index record without checking for.
getCombinedIdentifier()  : string
Returns a combined identifier of this file, i.e. the storage UID and the folder identifier separated by a colon ":".
getContents()  : string
Get the contents of this file
getCreationTime()  : int
Returns the creation time of the file as Unix timestamp
getExtension()  : string
Get the extension of this file in a lower-case variant
getFileType()  : FileType
Returns the fileType of this file basically there are only five main "file types" "audio" "image" "software" "text" "video" "other" see FileType enum
getForLocalProcessing()  : non-empty-string
Returns a path to a local version of this file to process it locally (e.g. with some system tool).
getHash()  : string
getHashedIdentifier()  : non-empty-string
getIdentifier()  : string
getImageDimension()  : ImageDimension
getMetaData()  : MetaDataAspect
Loads the metadata of a file in an encapsulated aspect
getMimeType()  : non-empty-string
Get the MIME type of this file
getModificationTime()  : int
Returns the date (as UNIX timestamp) the file was last modified.
getName()  : string
getNameWithoutExtension()  : string
Returns the basename (the name without extension) of this file.
getParentFolder()  : Folder
getProperties()  : array<non-empty-string, mixed>
Returns the properties of this object.
getProperty()  : mixed
Returns a property value
getPublicUri()  : UriInterface
getPublicUrl()  : string|null
Returns a publicly accessible URL for this file When file is marked as missing or deleted no url is returned
getResourceIdentifier()  : string
getSha1()  : non-empty-string
Gets SHA1 hash.
getSize()  : int<0, max>
MUST return the size of the file as unsigned int i.e. 0-max.
getStorage()  : ResourceStorage
getType()  : int
Returns the fileType of this file basically there are only five main "file types" "audio" "image" "software" "text" "video" "other" see FileType enum
getUid()  : int
Returns the uid of this file
getUpdatedProperties()  : array
Returns the names of all properties that have been updated in this record
hasProperty()  : bool
Checks if the file has a (metadata) property which can be retrieved by "getProperty"
isDeleted()  : bool
Returns TRUE if this file has been deleted
isImage()  : bool
Useful to find out if this file can be previewed or resized as image.
isIndexed()  : bool
Returns TRUE if this file is indexed
isMediaFile()  : bool
Useful to find out if this file has a file extension based on any of the registered media extensions
isMissing()  : bool
isPublished()  : bool
isTextFile()  : bool
Useful to find out if this file can be edited.
isType()  : bool
moveTo()  : FileInterface
Moves the file into the target folder
process()  : ProcessedFile
Returns a modified version of the file.
rename()  : FileInterface
Renames this file.
setContents()  : $this
Replace the current file contents with the given string
setDeleted()  : void
Marks this file as deleted. This should only be used inside the File Abstraction Layer, as it is a low-level API method.
setMissing()  : void
setStorage()  : $this
Sets the storage this file is located in. This is only meant for \TYPO3\CMS\Core\Resource-internal usage; don't use it to move files.
toArray()  : array<non-empty-string, mixed>
Returns an array representation of the file.
updateProperties()  : void
Updates the properties of this file, e.g. after re-indexing or moving it.

Properties

$deleted

If set to true, this file is regarded as being deleted.

protected bool $deleted = false

$name

The file name of this file

protected string $name = ''

$properties

Various file properties

protected array<non-empty-string, mixed> $properties = []

Note that all properties, which only the persisted (indexed) files have are stored in this overall properties array only. The only properties which really exist as object properties of the file object are the storage, the identifier, the fileName and the indexing status.

$updatedProperties

Contains the names of all properties that have been update since the instantiation of this object

protected array $updatedProperties = []

Methods

__construct()

Constructor for a file object. Should normally not be used directly, use the corresponding factory methods instead.

public __construct(array $fileData, ResourceStorage $storage[, array $metaData = [] ]) : mixed

Parameters

$fileData : array
$storage : ResourceStorage
$metaData : array = []

__toString()

public __toString() : string

Return values

string

_getPropertyRaw()

public _getPropertyRaw(string $key) : mixed

Parameters

$key : string

calculateChecksum()

Creates a MD5 hash checksum based on the combined identifier of the file, the files' mimetype and the systems' encryption key.

public calculateChecksum() : string

used to generate a thumbnail, and this hash is checked if valid

Return values

string —

the MD5 hash

checkActionPermission()

Check if a file operation (= action) is allowed for this file

public checkActionPermission(string $action) : bool

Parameters

$action : string

can be read, write, delete

Return values

bool

delete()

Deletes this file from its storage. This also means that this object becomes useless.

public delete() : bool

Return values

bool

exists()

Checks if this file exists. This should normally always return TRUE; it might only return FALSE when this object has been created from an index record without checking for.

public exists() : bool

Return values

bool —

TRUE if this file physically exists

getCombinedIdentifier()

Returns a combined identifier of this file, i.e. the storage UID and the folder identifier separated by a colon ":".

public getCombinedIdentifier() : string

Return values

string —

Combined storage and file identifier, e.g. StorageUID:path/and/fileName.png

getContents()

Get the contents of this file

public getContents() : string

Return values

string

getCreationTime()

Returns the creation time of the file as Unix timestamp

public getCreationTime() : int

Tags

throws
RuntimeException

Return values

int

getExtension()

Get the extension of this file in a lower-case variant

public getExtension() : string

Return values

string

getFileType()

Returns the fileType of this file basically there are only five main "file types" "audio" "image" "software" "text" "video" "other" see FileType enum

public getFileType() : FileType

Return values

FileType

getForLocalProcessing()

Returns a path to a local version of this file to process it locally (e.g. with some system tool).

public getForLocalProcessing([bool $writable = true ]) : non-empty-string

If the file is normally located on a remote storages, this creates a local copy. If the file is already on the local system, this only makes a new copy if $writable is set to TRUE.

Parameters

$writable : bool = true

Set this to FALSE if you only want to do read operations on the file.

Tags

throws
RuntimeException

Return values

non-empty-string

getHash()

public getHash() : string

Return values

string

getHashedIdentifier()

public getHashedIdentifier() : non-empty-string

Return values

non-empty-string

getIdentifier()

public getIdentifier() : string

Return values

string

getMimeType()

Get the MIME type of this file

public getMimeType() : non-empty-string

Return values

non-empty-string —

mime type

getModificationTime()

Returns the date (as UNIX timestamp) the file was last modified.

public getModificationTime() : int

Tags

throws
RuntimeException

Return values

int

getName()

public getName() : string

Return values

string

getNameWithoutExtension()

Returns the basename (the name without extension) of this file.

public getNameWithoutExtension() : string

Return values

string

getProperties()

Returns the properties of this object.

public getProperties() : array<non-empty-string, mixed>

Return values

array<non-empty-string, mixed>

getProperty()

Returns a property value

public getProperty(non-empty-string $key) : mixed

Parameters

$key : non-empty-string

getPublicUrl()

Returns a publicly accessible URL for this file When file is marked as missing or deleted no url is returned

public getPublicUrl() : string|null

WARNING: Access to the file may be restricted by further means, e.g. some web-based authentication. You have to take care of this yourself.

Return values

string|null —

NULL if file is deleted, the generated URL otherwise

getResourceIdentifier()

public getResourceIdentifier() : string

Return values

string

getSha1()

Gets SHA1 hash.

public getSha1() : non-empty-string

Return values

non-empty-string

getSize()

MUST return the size of the file as unsigned int i.e. 0-max.

public getSize() : int<0, max>

Tags

throws
RuntimeException

Return values

int<0, max>

getType()

Returns the fileType of this file basically there are only five main "file types" "audio" "image" "software" "text" "video" "other" see FileType enum

public getType() : int

Return values

int

getUid()

Returns the uid of this file

public getUid() : int

Return values

int

getUpdatedProperties()

Returns the names of all properties that have been updated in this record

public getUpdatedProperties() : array

Return values

array

hasProperty()

Checks if the file has a (metadata) property which can be retrieved by "getProperty"

public hasProperty(string $key) : bool

Parameters

$key : string

Return values

bool

isDeleted()

Returns TRUE if this file has been deleted

public isDeleted() : bool

Return values

bool

isImage()

Useful to find out if this file can be previewed or resized as image.

public isImage() : bool

Return values

bool —

true if File has an image-extension according to $GLOBALS['TYPO3_CONF_VARS']['GFX']['imagefile_ext']

isIndexed()

Returns TRUE if this file is indexed

public isIndexed() : bool

Return values

bool

isMediaFile()

Useful to find out if this file has a file extension based on any of the registered media extensions

public isMediaFile() : bool

Return values

bool —

true if File is a media-extension according to $GLOBALS['TYPO3_CONF_VARS']['SYS']['mediafile_ext']

isMissing()

public isMissing() : bool

Return values

bool

isPublished()

public isPublished() : bool

Return values

bool

isTextFile()

Useful to find out if this file can be edited.

public isTextFile() : bool

Return values

bool —

true if File is a text-based file extension according to $GLOBALS['TYPO3_CONF_VARS']['SYS']['textfile_ext']

moveTo()

Moves the file into the target folder

public moveTo(Folder $targetFolder[, string|null $targetFileName = null ][, DuplicationBehavior $conflictMode = DuplicationBehavior::RENAME ]) : FileInterface

Parameters

$targetFolder : Folder

Folder to move file into.

$targetFileName : string|null = null

an optional destination fileName

$conflictMode : DuplicationBehavior = DuplicationBehavior::RENAME

Tags

throws
RuntimeException

Return values

FileInterface —

This file object, with updated properties.

process()

Returns a modified version of the file.

public process(string $taskType, array $configuration) : ProcessedFile

Parameters

$taskType : string

The task type of this processing

$configuration : array

the processing configuration, see manual for that

Return values

ProcessedFile

setContents()

Replace the current file contents with the given string

public setContents(string $contents) : $this

Parameters

$contents : string

Return values

$this

setDeleted()

Marks this file as deleted. This should only be used inside the File Abstraction Layer, as it is a low-level API method.

public setDeleted() : void

setMissing()

public setMissing(bool $missing) : void

Parameters

$missing : bool

setStorage()

Sets the storage this file is located in. This is only meant for \TYPO3\CMS\Core\Resource-internal usage; don't use it to move files.

public setStorage(ResourceStorage $storage) : $this

Parameters

$storage : ResourceStorage

Return values

$this

toArray()

Returns an array representation of the file.

public toArray() : array<non-empty-string, mixed>

(This is used by the generic listing module vidi when displaying file records.)

Return values

array<non-empty-string, mixed> —

Array of main data of the file. Don't rely on all data to be present here, it's just a selection of the most relevant information.

updateProperties()

Updates the properties of this file, e.g. after re-indexing or moving it.

public updateProperties(array $properties) : void

By default, only properties that exist as a key in the $properties array are overwritten. If you want to explicitly unset a property, set the corresponding key to NULL in the array.

NOTE: This method should not be called from outside the File Abstraction Layer (FAL)!

Parameters

$properties : array
On this page