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.

Table of Contents

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

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.

Constants

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'

Properties

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

$taskType

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

protected string $taskType

$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

Methods

__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 ][, DuplicationBehavior $conflictMode = DuplicationBehavior::RENAME ]) : File
Parameters
$targetFolder : Folder

Folder to copy file into.

$targetFileName : string = null

an optional destination fileName

$conflictMode : DuplicationBehavior = DuplicationBehavior::RENAME
Tags
throws
RuntimeException
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
Tags
throws
RuntimeException
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

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

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
Tags
throws
RuntimeException
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()

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

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
Tags
throws
RuntimeException
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>

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
Tags
todo

will return an instance of FileType enum in TYPO3 v14.0

Attributes
#[ReturnTypeWillChange]
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']

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 ][, DuplicationBehavior $conflictMode = DuplicationBehavior::RENAME ]) : File
Parameters
$targetFolder : Folder

Folder to move file into.

$targetFileName : string = null

an optional destination fileName

$conflictMode : DuplicationBehavior = DuplicationBehavior::RENAME
Tags
throws
RuntimeException
Return values
File —

This file object, with updated properties.

needsReprocessing()

Checks if the ProcessedFile needs reprocessing

public needsReprocessing() : bool
Return values
bool

setContents()

Replace the current file contents with the given string

public setContents(string $contents) : $this
Parameters
$contents : string
Tags
throws
BadMethodCallException
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
Tags
throws
RuntimeException

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> 

        

        
    




    

    

                            

            

                            
    

        On this page

        
    


            

                    

        

    

        

            
Search results