TYPO3 main API: ProcessedFile

ProcessedFile extends AbstractFile

Representation of a specific processed version of a file. These are created by the FileProcessingService, which in turn uses helper classes for doing the actual file processing. See there for a detailed description.

Objects of this class may be freshly created during runtime or being fetched from the database. The latter indicates that the file has been processed earlier and was then cached.

Each processed file—besides belonging to one file—has been created for a certain task (context) and configuration. All these won't change during the lifetime of a processed file; the only thing that can change is the original file, or rather it's contents. In that case, the processed file has to be processed again. Detecting this is done via comparing the current SHA1 hash of the original file against the one it had at the time the file was processed. The configuration of a processed file indicates what should be done to the original file to create the processed version. This may include things like cropping, scaling, rotating, flipping or using some special magic. A file may also meet the expectations set in the configuration without any processing. In that case, the ProcessedFile object still exists, but there is no physical file directly linked to it. Instead, it then redirects most method calls to the original file object. The data of these objects are also stored in the database, to indicate that no processing is required. With such files, the identifier and name fields in the database are empty to show this.

Constants

CONTEXT_IMAGECROPSCALEMASK = 'Image.CropScaleMask': Standard processing context for the frontend, that was previously in \TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer::getImgResource which only takes cropping, masking and scaling into account
CONTEXT_IMAGEPREVIEW = 'Image.Preview': Basic processing context to get a processed image with smaller width/height to render a preview
FILETYPE_APPLICATION = 5: Any kind of application
FILETYPE_AUDIO = 3: Any kind of audio file
FILETYPE_IMAGE = 2: Any kind of image
FILETYPE_TEXT = 1: Any kind of text
FILETYPE_UNKNOWN = 0: any other file
FILETYPE_VIDEO = 4: Any kind of video

Properties

$deleted : bool: If set to true, this file is regarded as being deleted.
$identifier : string: The identifier of this file to identify it on the storage.
$name : string: The file name of this file
$originalFile : File: Reference to the original file this processed file has been created from.
$originalFileSha1 : string|null: The SHA1 hash of the original file this processed version has been created for.
$processingConfiguration : array<string|int, mixed>|null: Processing configuration
$processingUrl : string: If this is set, this URL is used as public URL This MUST be a fully qualified URL including host
$properties : array<non-empty-string, mixed>: Various file properties
$storage : ResourceStorage|null: The storage this file is located in
$task : TaskInterface|null
$taskType : string: Processing context, i.e. the type of processing done
$taskTypeRegistry : TaskTypeRegistry
$updated : bool: A flag that shows if this object has been updated during its lifetime, i.e. the file has been replaced with a new one.

Methods

__construct() : mixed: Constructor for a processed file object. Should normally not be used directly, use the corresponding factory methods instead.
copyTo() : File: Copies this file into a target folder
delete() : bool: Delete processed file
exists() : bool: Checks if this file exists.
generateProcessedFileNameWithoutExtension() : string: Generate the name of the new File
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
getForLocalProcessing() : non-empty-string: Returns a path to a local version of this file to process it locally (e.g. with some system tool).
getHashedIdentifier() : non-empty-string
getIdentifier() : non-empty-string: Get the identifier of the file
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() : non-empty-string: Get the name of the file
getNameWithoutExtension() : string: Returns the basename (the name without extension) of this file.
getOriginalFile() : File: Getter for the Original, unprocessed File
getParentFolder() : FolderInterface
getProcessingConfiguration() : array<string|int, mixed>: Returns the processing information
getProperties() : array<non-empty-string, mixed>: Returns the properties of this object.
getProperty() : mixed: Getter for file-properties
getPublicUrl() : non-empty-string|null: Returns a publicly accessible URL for this file
getSha1() : non-empty-string: Returns the Sha1 of this file
getSize() : int<0, max>: MUST return the size of the file as unsigned int i.e. 0-max.
getStorage() : ResourceStorage
getTask() : TaskInterface: Returns the task object associated with this processed file.
getTaskIdentifier() : string: Getter for the task identifier.
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
hasProperty() : bool: Returns true if the given property key exists for this file.
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() : false: 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
isNew() : bool: Checks whether the ProcessedFile Object is newly created
isOutdated() : bool: Returns TRUE if the original file of this file changed and the file should be processed again.
isPersisted() : bool: Checks whether the ProcessedFile already has an entry in sys_file_processedfile table
isProcessed() : bool: Returns TRUE if this file is already processed.
isTextFile() : bool: Useful to find out if this file can be edited.
isType() : bool
isUpdated() : bool: Checks whether the object since last reconstitution, and therefore needs persistence again
moveTo() : File: Moves the file into the target folder
needsReprocessing() : bool: Checks if the ProcessedFile needs reprocessing
rename() : FileInterface: Renames this file.
setContents() : $this: Replace the current file contents with the given string
setDeleted() : mixed: Marks this file as deleted. This should only be used inside the File Abstraction Layer, as it is a low-level API method.
setIdentifier() : $this: Set the identifier of this file
setName() : void: Sets a new file name
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.
setUsesOriginalFile() : void: Defines that the original file should be used.
toArray() : array<non-empty-string, mixed>: Basic array function for the DB update
updateProcessingUrl() : void
updateProperties() : void: Updates properties of this object. Do not use this to reconstitute an object from the database; use reconstituteFromDatabaseRecord() instead!
updateWithLocalFile() : void: Injects a local file, which is a processing result into the object.
usesOriginalFile() : bool
calculateChecksum() : string: Returns a unique checksum for this file's processing configuration and original file.
isUnchanged() : bool: Returns TRUE if this file has not been changed during processing (i.e., we just deliver the original file)
reconstituteFromDatabaseRecord() : void: Creates a ProcessedFile object from a database record.

CONTEXT_IMAGECROPSCALEMASK

Standard processing context for the frontend, that was previously in \TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer::getImgResource which only takes cropping, masking and scaling into account


    public
        mixed
    CONTEXT_IMAGECROPSCALEMASK
    = 'Image.CropScaleMask'

CONTEXT_IMAGEPREVIEW

Basic processing context to get a processed image with smaller width/height to render a preview


    public
        mixed
    CONTEXT_IMAGEPREVIEW
    = 'Image.Preview'

FILETYPE_APPLICATION

Any kind of application

Deprecated

will be removed in TYPO3 v14, use TYPO3\CMS\Core\Resource\FileType::APPLICATION instead


    public
        mixed
    FILETYPE_APPLICATION
    = 5

FILETYPE_AUDIO

Any kind of audio file

Deprecated

will be removed in TYPO3 v14, use TYPO3\CMS\Core\Resource\FileType::AUDIO instead


    public
        mixed
    FILETYPE_AUDIO
    = 3

FILETYPE_IMAGE

Any kind of image

Deprecated

will be removed in TYPO3 v14, use TYPO3\CMS\Core\Resource\FileType::IMAGE instead


    public
        mixed
    FILETYPE_IMAGE
    = 2

FILETYPE_TEXT

Any kind of text

Deprecated

will be removed in TYPO3 v14, use TYPO3\CMS\Core\Resource\FileType::TEXT instead


    public
        mixed
    FILETYPE_TEXT
    = 1

FILETYPE_UNKNOWN

any other file

Deprecated

will be removed in TYPO3 v14, use TYPO3\CMS\Core\Resource\FileType::UNKNOWN instead


    public
        mixed
    FILETYPE_UNKNOWN
    = 0

FILETYPE_VIDEO

Any kind of video

Deprecated

will be removed in TYPO3 v14, use TYPO3\CMS\Core\Resource\FileType::VIDEO instead


    public
        mixed
    FILETYPE_VIDEO
    = 4

$deleted

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


    protected
        bool
    $deleted
     = false

$identifier

The identifier of this file to identify it on the storage.


    protected
        string
    $identifier

On some drivers, this is the path to the file, but drivers could also just provide any other unique identifier for this file on the specific storage.

$name

The file name of this file


    protected
        string
    $name

$originalFile

Reference to the original file this processed file has been created from.


    protected
        File
    $originalFile

$originalFileSha1

The SHA1 hash of the original file this processed version has been created for.


    protected
        string|null
    $originalFileSha1

Is used for detecting changes if the original file has been changed and thus we have to recreate this processed file.

$processingConfiguration

Processing configuration


    protected
        array<string|int, mixed>|null
    $processingConfiguration

$processingUrl

If this is set, this URL is used as public URL This MUST be a fully qualified URL including host


    protected
        string
    $processingUrl

$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.

$storage

The storage this file is located in


    protected
        ResourceStorage|null
    $storage

$task


    protected
        TaskInterface|null
    $task
     = null

$taskType

Processing context, i.e. the type of processing done


    protected
        string
    $taskType

$taskTypeRegistry


    protected
        TaskTypeRegistry
    $taskTypeRegistry

$updated

A flag that shows if this object has been updated during its lifetime, i.e. the file has been replaced with a new one.


    protected
        bool
    $updated
     = false

__construct()

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


    public
                    __construct(File $originalFile, string $taskType, array<string|int, mixed> $processingConfiguration[, array<string|int, mixed>|null $databaseRow = null ]) : mixed

Parameters

$originalFile : File
$taskType : string
$processingConfiguration : array<string|int, mixed>
$databaseRow : array<string|int, mixed>|null = null

copyTo()

Copies this file into a target folder


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

Parameters

$targetFolder : Folder: Folder to copy file into.
$targetFileName : string = null: an optional destination fileName
$conflictMode : string|DuplicationBehavior = DuplicationBehavior::RENAME

Return values

File —

The new (copied) file.

delete()

Delete processed file


    public
                    delete([bool $force = false ]) : bool

Parameters

$force : bool = false

Return values

bool

exists()

Checks if this file exists.


    public
                    exists() : bool

Since the original file may reside in a different storage we ask the original file if it exists in case the processed is representing it

Return values

bool —

TRUE if this file physically exists

generateProcessedFileNameWithoutExtension()

Generate the name of the new File


    public
                    generateProcessedFileNameWithoutExtension() : string

Return values

string

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

Return values

int

getExtension()

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


    public
                    getExtension() : string

Return values

string

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.

Return values

non-empty-string

getHashedIdentifier()


    public
                    getHashedIdentifier() : non-empty-string

Return values

non-empty-string

getIdentifier()

Get the identifier of the file


    public
                    getIdentifier() : non-empty-string

If there is no processed file in the file system (as the original file did not have to be modified e.g. when the original image is in the boundaries of the maxW/maxH stuff), then just return the identifier of the original file

Return values

non-empty-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

Return values

int

getName()

Get the name of the file


    public
                    getName() : non-empty-string

If there is no processed file in the file system (as the original file did not have to be modified e.g. when the original image is in the boundaries of the maxW/maxH stuff) then just return the name of the original file

Return values

non-empty-string

getNameWithoutExtension()

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


    public
                    getNameWithoutExtension() : string

Return values

string

getOriginalFile()

Getter for the Original, unprocessed File


    public
                    getOriginalFile() : File

Return values

File

getParentFolder()


    public
                    getParentFolder() : FolderInterface

Return values

FolderInterface

getProcessingConfiguration()

Returns the processing information


    public
                    getProcessingConfiguration() : array<string|int, mixed>

Return values

array<string|int, mixed>

getProperties()

Returns the properties of this object.


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

Return values

array<non-empty-string, mixed>

getProperty()

Getter for file-properties


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

Parameters

$key : non-empty-string

getPublicUrl()

Returns a publicly accessible URL for this file


    public
                    getPublicUrl() : non-empty-string|null

Return values

non-empty-string|null —

NULL if file is deleted, the generated URL otherwise

getSha1()

Returns the Sha1 of this file


    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>

Return values

int<0, max>

getStorage()


    public
                    getStorage() : ResourceStorage

Return values

ResourceStorage

getTask()

Returns the task object associated with this processed file.


    public
                    getTask() : TaskInterface

Return values

TaskInterface

getTaskIdentifier()

Getter for the task identifier.


    public
                    getTaskIdentifier() : string

Return values

string

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 —

$fileType

getUid()

Returns the uid of this file


    public
                    getUid() : int

Return values

int

hasProperty()

Returns true if the given property key exists for this file.


    public
                    hasProperty(non-empty-string $key) : bool

Parameters

$key : non-empty-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() : false

Return values

false

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']

isNew()

Checks whether the ProcessedFile Object is newly created


    public
                    isNew() : bool

Return values

bool

isOutdated()

Returns TRUE if the original file of this file changed and the file should be processed again.


    public
                    isOutdated() : bool

Return values

bool

isPersisted()

Checks whether the ProcessedFile already has an entry in sys_file_processedfile table


    public
                    isPersisted() : bool

Return values

bool

isProcessed()

Returns TRUE if this file is already processed.


    public
                    isProcessed() : 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']

isType()


    public
                    isType(FileType $fileType) : bool

Parameters

$fileType : FileType

Return values

bool

isUpdated()

Checks whether the object since last reconstitution, and therefore needs persistence again


    public
                    isUpdated() : bool

Return values

bool

moveTo()

Moves the file into the target folder


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

Parameters

$targetFolder : Folder: Folder to move file into.
$targetFileName : string = null: an optional destination fileName
$conflictMode : string|DuplicationBehavior = DuplicationBehavior::RENAME

Return values

File —

This file object, with updated properties.

needsReprocessing()

Checks if the ProcessedFile needs reprocessing


    public
                    needsReprocessing() : bool

Return values

bool

rename()

Renames this file.


    public
                    rename(non-empty-string $newName[, string|DuplicationBehavior $conflictMode = DuplicationBehavior::RENAME ]) : FileInterface

Parameters

$newName : non-empty-string: The new file name
$conflictMode : string|DuplicationBehavior = DuplicationBehavior::RENAME

Return values

FileInterface

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() : mixed

setIdentifier()

Set the identifier of this file


    public
                    setIdentifier(string $identifier) : $this

Parameters

$identifier : string

Internal

Should only be used by other parts of the File API (e.g. drivers after moving a file)

Return values

$this

setName()

Sets a new file name


    public
                    setName(string $name) : void

Parameters

$name : string

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

Internal

Should only be used by other parts of the File API (e.g. drivers after moving a file)

Return values

$this

setUsesOriginalFile()

Defines that the original file should be used.


    public
                    setUsesOriginalFile() : void

toArray()

Basic array function for the DB update


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

Return values

array<non-empty-string, mixed>

updateProcessingUrl()


    public
                    updateProcessingUrl(string $url) : void

Parameters

$url : string

updateProperties()

Updates properties of this object. Do not use this to reconstitute an object from the database; use reconstituteFromDatabaseRecord() instead!


    public
                    updateProperties(array<string|int, mixed> $properties) : void

Parameters

$properties : array<string|int, mixed>

updateWithLocalFile()

Injects a local file, which is a processing result into the object.


    public
                    updateWithLocalFile(string $filePath) : void

Parameters

$filePath : string

usesOriginalFile()


    public
                    usesOriginalFile() : bool

Return values

bool

calculateChecksum()

Returns a unique checksum for this file's processing configuration and original file.


    protected
                    calculateChecksum() : string

Return values

string

isUnchanged()

Returns TRUE if this file has not been changed during processing (i.e., we just deliver the original file)


    protected
                    isUnchanged() : bool

Return values

bool

reconstituteFromDatabaseRecord()

Creates a ProcessedFile object from a database record.


    protected
                    reconstituteFromDatabaseRecord(array<string|int, mixed> $databaseRow) : void

Parameters

$databaseRow : array<string|int, mixed>

ProcessedFile extends AbstractFile

Table of Contents

Constants

Properties

Methods

Constants

CONTEXT_IMAGECROPSCALEMASK

CONTEXT_IMAGEPREVIEW

FILETYPE_APPLICATION

Tags

FILETYPE_AUDIO

Tags

FILETYPE_IMAGE

Tags

FILETYPE_TEXT

Tags

FILETYPE_UNKNOWN

FILETYPE_VIDEO

Tags

Properties

$deleted

$identifier

$name

$originalFile

$originalFileSha1

$processingConfiguration

$processingUrl

$properties

$storage

$task

$taskType

$taskTypeRegistry

$updated

Methods

__construct()

Parameters

copyTo()

Parameters

Tags

Return values

delete()

Parameters

Return values

exists()

Return values

generateProcessedFileNameWithoutExtension()

Return values

getCombinedIdentifier()

Return values

getContents()

Tags

Return values

getCreationTime()

Tags

Return values

getExtension()

Return values

getForLocalProcessing()

Parameters

Tags

Return values

getHashedIdentifier()

Return values

getIdentifier()

Return values

getMimeType()

Tags

Return values

getModificationTime()

Tags

Return values

getName()

Return values

getNameWithoutExtension()

Return values

getOriginalFile()

Return values

getParentFolder()

Return values

getProcessingConfiguration()