Concrete\Core\Entity\File\Version

class Version implements ObjectInterface (View source)

Represents a version of a file.

Traits

ObjectTrait

Constants

UT_REPLACE_FILE	Update type: file replaced.
UT_TITLE	Update type: title updated.
UT_DESCRIPTION	Update type: description updated.
UT_TAGS	Update type: tags modified.
UT_EXTENDED_ATTRIBUTE	Update type: extended attributes changed.
UT_CONTENTS	Update type: contents changed.
UT_RENAME	Update type: file version renamed.

Properties

protected File	$file	The associated File instance.
protected int	$fvID	The progressive file version identifier.
protected string	$fvFilename	The name of the file.
protected string	$fvPrefix	The path prefix used to store the file in the file system.
protected DateTime	$fvDateAdded	The date/time when the file version has been added.
protected DateTime	$fvActivateDateTime	The date/time when the file version has been approved.
protected bool	$fvIsApproved	Is this version the approved one for the associated file?
protected int	$fvAuthorUID	The ID of the user that created the file version.
protected int	$fvApproverUID	The ID of the user that approved the file version.
protected int	$fvSize	The size (in bytes) of the file version.
protected string\|null	$fvTitle	The title of the file version.
protected string\|null	$fvDescription	The description of the file version.
protected string\|null	$fvExtension	The extension of the file version.
protected string\|null	$fvTags	The tags assigned to the file version (separated by a newline character - '\n').
protected int	$fvType	The type of the file version.
protected bool	$fvHasListingThumbnail	Does this file version has a thumbnail to be used for file listing?
protected bool	$fvHasDetailThumbnail	Does this file version has a thumbnail to be used used for details?
private ImageInterface\|false\|null	$imagineImage	The currently loaded Image instance.

Methods

CategoryInterface

getObjectAttributeCategory()

No description

AttributeValueInterface|null

getAttributeValueObject(AttributeKeyInterface|string $ak, bool $createIfNotExists = false)

No description

getAttribute($ak, $mode = false)

No description

from ObjectTrait

Value

getAttributeValue($ak)

No description

from ObjectTrait

clearAttribute($ak, bool $doReindexImmediately = true)

No description

from ObjectTrait

Value

setAttribute($ak, mixed $value, bool $doReindexImmediately = true)

Sets the attribute of a user info object to the specified value, and saves it in the database.

from ObjectTrait

__construct()

Initialize the instance.

static Version

add(File $file, string $filename, string $prefix, array $data = [])

Add a new file version.

static string

cleanTags(string $tagsStr)

Normalize the tags separator, remove empty tags.

setFile(File $file)

Set the associated File instance.

File

getFile()

Get the associated File instance.

int

getFileID()

Get the ID of the associated file instance.

string

getFileUUID()

Get the ID of the associated file instance.

bool

hasFileUUID()

No description

setFileVersionID(int $fvID)

Set the progressive file version identifier.

int

getFileVersionID()

Get the progressive file version identifier.

rename(string $filename)

Rename the file.

updateFile(string $filename, string $prefix)

Update the filename and the path prefix of the file.

setFilename(string $filename)

Set the name of the file.

string

getFileName()

Get the name of the file.

string

getPrefix()

Get the path prefix used to store the file in the file system.

DateTime

getDateAdded()

Get the date/time when the file version has been added.

DateTime|null

getActivateDateTime()

Get the date/time when the file version has been activated (or NULL if the file version is not approved).

approve()

Mark this file version as approved (and disapprove all the other versions of the file).

deny()

Mark this file version as not approved.

bool

isApproved()

Is this version the approved one for the associated file?

int

getAuthorUserID()

Get the ID of the user that created the file version.

string

getAuthorName()

Get the username of the user that created the file version (or "Unknown").

int

getApproverUserID()

Get the ID of the user that approved the file version.

string

getApproverName()

Get the username of the user that approved the file version (or "Unknown").

int

getFullSize()

Get the file size of the file (in bytes).

string

getSize()

Get the formatted file size.

updateTitle(string $title)

Update the title of the file.

null|string

getTitle()

Get the title of the file version.

updateDescription(string $descr)

Update the description of the file.

null|string

getDescription()

Get the description of the file version.

null|string

getExtension()

Get the extension of the file version.

updateTags(string $tags)

Update the tags associated to the file.

string[]

getTagsList()

Get the tags assigned to the file version (as a list of strings).

null|string

getTags()

Get the tags assigned to the file version (one tag per line - lines are separated by '\n').

string|false

getMimeType()

Get the mime type of the file if known.

Type

getTypeObject()

Get the type of the file.

string

getType()

Get the name of the file type.

string

getDisplayType()

Get the localized name of the file type.

string

getGenericTypeText($includeExtension = false)

Get the localized name of the generic category type.

logVersionUpdate(int $updateTypeID, int $updateTypeAttributeID = 0)

Log updates to files.

string[]

getVersionLogComments()

Get an array containing human-readable descriptions of everything that happened to this file version.

string|null

getRelativePath()

Get the path to the file relative to the webroot (may not exist).

string|null

getURL()

Get an URL that points to the file on disk (if not available, you'll get the result of the getDownloadURL method).

ConfigurationInterface|null

getFileStorageLocationConfiguration()

Get File Storage Location Configuration object of this file.

bool

hasPublicURL()

If the file storage location of this file has public URL or not.

URLInterface

getDownloadURL()

Get an URL that can be used to download the file.

URLInterface

getForceDownloadURL()

Get an URL that can be used to download the file (it will force the download of all file types, even if the browser can display them).

Response

buildForceDownloadResponse()

Get a Response instance that will force the browser to download the file, even if the browser can display it.

bool

canView()

Check if there is a viewer for the type of the file.

bool

canEdit()

Check if there is an editor for the type of the file.

Version

duplicate()

Create a new (unapproved) copy of this file version.

duplicateUnderlyingFile()

Duplicate the underlying file and assign its new position to this instance.

delete(bool $deleteFilesAndThumbnails = false)

Delete this version of the file.

File

getFileResource()

Get an abstract object to work with the actual file resource (note: this is NOT a concrete5 File object).

updateContents(string $contents, bool $rescanThumbnails = true)

Update the contents of the file.

string|null

getFileContents()

Get the contents of the file.

null|int

refreshAttributes(bool $rescanThumbnails = true)

Rescan all the attributes of this file version.

FileValue[]

getAttributes()

Get the list of attributes associated to this file version.

ImageInterface|null

getImagineImage()

Get an \Imagine\Image\ImageInterface representing the image.

bool

hasImagineImage()

Does the \Imagine\Image\ImageInterface instance have already been loaded?

releaseImagineImage()

Unload the loaded Image instance.

bool

refreshThumbnails(bool $deleteExistingThumbnails)

Create missing thumbnails (or re-create all the thumbnails).

generateThumbnail(Version $type)

Generate a thumbnail for a specific thumbnail type version.

importThumbnail(Version $version, string $path)

Import an existing file as a thumbnail type version.

string|null

getThumbnailURL(Version|string $type)

Get the URL of a thumbnail type.

Thumbnail[]

getThumbnails()

Get the list of all the thumbnails.

string

getDetailThumbnailImage()

Get the HTML that renders the thumbnail for the details (a generic type icon if the thumbnail does not exist).

string

getListingThumbnailImage()

Get the HTML that renders the thumbnail for the file listing (a generic type icon if the thumbnail does not exist).

deleteThumbnail(Version|string $type)

Delete the thumbnail for a specific thumbnail type version.

updateThumbnailStorageLocation(Version|string $type, StorageLocation $location)

Move the thumbnail of a specific thumbnail type version to a new storage location.

duplicateUnderlyingThumbnailFiles(Version|string $type, Version $source)

Copy the thumbnail of a specific thumbnail type version from another file version (useful for instance when duplicating a file).

stdClass

getJSONObject()

Get a representation of this Version instance that's easily serializable.

forceDownload() deprecated

No description

bool

hasThumbnail(int $level) deprecated

No description

bool

rescanThumbnails() deprecated

No description

save(bool $flush = true)

Save the instance changes.

Details

at line 1298
`CategoryInterface getObjectAttributeCategory()`

No description

Return Value

CategoryInterface

at line 1385
`AttributeValueInterface|null getAttributeValueObject(AttributeKeyInterface|string $ak, bool $createIfNotExists = false)`

No description

Parameters

AttributeKeyInterface\|string	$ak	An attribute key instance (or its handle)
bool	$createIfNotExists	Shall the generic attribute value be created if it does not already exist?

Return Value

AttributeValueInterface|null

in ObjectTrait at line 24
`getAttribute($ak, $mode = false)`

No description

Parameters

	$ak
	$mode

at line 316
`static Version add(File $file, string $filename, string $prefix, array $data = [])`

Add a new file version.

You should call refreshAttributes in order to update the size, extension, type and other attributes.

Parameters

File	$file	the File instance associated to this version
string	$filename	The name of the file
string	$prefix	the path prefix used to store the file in the file system
array	$data	Valid array keys are { `@var int\|null $uID the ID of the user that creates the file version (if not specified or empty: we'll assume the currently user logged in user) @var string $fvTitle the title of the file version @var string $fvDescription the description of the file version @var string $fvTags the tags to be assigned to the file version (separated by newlines and/or commas) @var bool $fvIsApproved Is this version the approved one for the associated file? (default: true)` }

Return Value

Version

at line 370
`static string cleanTags(string $tagsStr)`

Normalize the tags separator, remove empty tags.

Parameters

string

$tagsStr

The list of tags, delimited by '\n', '\r' or ','

Return Value

string

at line 389
`setFile(File $file)`

Set the associated File instance.

Parameters

$fvID

at line 448
`int getFileVersionID()`

Get the progressive file version identifier.

Return Value

int

at line 458
`rename(string $filename)`

Rename the file.

Parameters

string

$filename

at line 489
`updateFile(string $filename, string $prefix)`

Update the filename and the path prefix of the file.

Parameters

string	$filename	The new name of file
string	$prefix	The new path prefix

at line 502
`setFilename(string $filename)`

Set the name of the file.

Parameters

at line 551
`approve()`

Examples

123 KB

at line 681
`updateTitle(string $title)`

Update the title of the file.

Parameters

string

$title

at line 696
`null|string getTitle()`

Get the title of the file version.

Return Value

null|string

at line 706
`updateDescription(string $descr)`

Update the description of the file.

Parameters

string

Get an array containing human-readable descriptions of everything that happened to this file version.

Return Value

string[]

at line 942
`string|null getRelativePath()`

Get the path to the file relative to the webroot (may not exist).

Return NULL if the file storage location is invalid. If the storage location does not support relative paths, you'll get the URL to the file (or the download URL if the file is not directly accessible).

Return Value

string|null

Examples

/application/files/0000/0000/0000/file.png

at line 971
`string|null getURL()`

Get an URL that points to the file on disk (if not available, you'll get the result of the getDownloadURL method).

Get an URL that can be used to download the file.

Create a new (unapproved) copy of this file version.

string|null

return NULL if the actual file does not exist or can't be read

at line 1313
`null|int refreshAttributes(bool $rescanThumbnails = true)`

Rescan all the attributes of this file version.

This will run any type-based import routines, and store those attributes, generate thumbnails, etc...

Parameters

bool

$rescanThumbnails

Should thumbnails be rescanned as well?

Return Value

null|int

Return one of the \Concrete\Core\File\Importer::E_... constants in case of errors, NULL otherwise.

at line 1373
`FileValue[] getAttributes()`

Get the list of attributes associated to this file version.

Return Value

FileValue[]

at line 1409
`ImageInterface|null getImagineImage()`

Get an \Imagine\Image\ImageInterface representing the image.

Return Value

ImageInterface|null

return NULL if the image coulnd't be read, an ImageInterface otherwise

at line 1459
`bool hasImagineImage()`

Does the \Imagine\Image\ImageInterface instance have already been loaded?

Return Value

bool

at line 1467
`releaseImagineImage()`

Unload the loaded Image instance.

at line 1483
`bool refreshThumbnails(bool $deleteExistingThumbnails)`

Create missing thumbnails (or re-create all the thumbnails).

Parameters

bool

$deleteExistingThumbnails

Set to true to delete existing thumbnails (they will be re-created from scratch)

Return Value

bool	return true on success, false on failure (file is not an image, problems during image processing, ...)

at line 1556
`generateThumbnail(Version $type)`

Generate a thumbnail for a specific thumbnail type version.

Parameters

Version

$type

at line 1666
`importThumbnail(Version $version, string $path)`

Import an existing file as a thumbnail type version.

Parameters

Version	$version
string	$path

at line 1714
`string|null getThumbnailURL(Version|string $type)`

Get the URL of a thumbnail type.

If the thumbnail is smaller than the image (or if the file does not satisfy the Conditional Thumbnail criterias) you'll get the URL of the image itself.

Please remark that the path is resolved using the default core path resolver: avoid using this method when you have access to the resolver instance.

Parameters

Version|string

$type

the thumbnail type version (or its handle)

Return Value

string|null

return NULL if the thumbnail does not exist and the file storage location is invalid

Examples

/application/files/thumbnails/file_manager_listing/0000/0000/0000/file.png

at line 1777
`Thumbnail[] getThumbnails()`

Get the list of all the thumbnails.

Return Value

Thumbnail[]

Exceptions

InvalidDimensionException

at line 1808
`string getDetailThumbnailImage()`

Get the HTML that renders the thumbnail for the details (a generic type icon if the thumbnail does not exist).

Return the thumbnail for an image or a generic type icon for a file.

Return Value

string

at line 1847
`string getListingThumbnailImage()`

Get the HTML that renders the thumbnail for the file listing (a generic type icon if the thumbnail does not exist).

Return Value

string

at line 1907
`deleteThumbnail(Version|string $type)`

Delete the thumbnail for a specific thumbnail type version.

Parameters

Version|string

$type

the thumbnail type version (or its handle)

at line 1942
`updateThumbnailStorageLocation(Version|string $type, StorageLocation $location)`

Move the thumbnail of a specific thumbnail type version to a new storage location.

Parameters

Version\|string	$type	the thumbnail type version (or its handle)
StorageLocation	$location	The destination storage location

at line 1965
`duplicateUnderlyingThumbnailFiles(Version|string $type, Version $source)`

Copy the thumbnail of a specific thumbnail type version from another file version (useful for instance when duplicating a file).

Parameters

Version\|string	$type	the thumbnail type version (or its handle)
Version	$source	The File Version instance to copy the thumbnail from

at line 1989
`stdClass getJSONObject()`

Get a representation of this Version instance that's easily serializable.

Return Value

stdClass

A \stdClass instance with all the information about a file (including permissions)

at line 2038
`forceDownload() deprecated`

deprecated Use buildForceDownloadResponse

No description

at line 2058
`bool hasThumbnail(int $level) deprecated`

deprecated

No description

Parameters

int

$level

Return Value

bool

at line 2075
`bool rescanThumbnails() deprecated`

deprecated use refreshThumbnails(true) instead

No description

Return Value

bool

at line 2085
`protected save(bool $flush = true)`

Save the instance changes.

Parameters

bool

$flush

Flush the EM cache?

Version

Traits

Constants

Properties

Methods

Details

at line 1298 CategoryInterface getObjectAttributeCategory()

Return Value

See also

at line 1385 AttributeValueInterface|null getAttributeValueObject(AttributeKeyInterface|string $ak, bool $createIfNotExists = false)

Parameters

Return Value

See also

in ObjectTrait at line 24 getAttribute($ak, $mode = false)

Parameters

in ObjectTrait at line 36 Value getAttributeValue($ak)

Parameters

Return Value

in ObjectTrait at line 48 clearAttribute($ak, bool $doReindexImmediately = true)

Parameters

in ObjectTrait at line 72 Value setAttribute($ak, mixed $value, bool $doReindexImmediately = true)

Parameters

Return Value

at line 292 __construct()

at line 316 static Version add(File $file, string $filename, string $prefix, array $data = [])

Parameters

Return Value

at line 370 static string cleanTags(string $tagsStr)

Parameters

Return Value

at line 389 setFile(File $file)

Parameters

at line 399 File getFile()

Return Value

at line 409 int getFileID()

Return Value

at line 419 string getFileUUID()

Return Value

at line 428 bool hasFileUUID()

Return Value

at line 438 setFileVersionID(int $fvID)

Parameters

at line 448 int getFileVersionID()

Return Value

at line 458 rename(string $filename)

Parameters

at line 489 updateFile(string $filename, string $prefix)

Parameters

at line 502 setFilename(string $filename)

Parameters

at line 512 string getFileName()

Return Value

at line 522 string getPrefix()

Return Value

at line 532 DateTime getDateAdded()

Return Value

at line 542 DateTime|null getActivateDateTime()

Return Value

at line 551 approve()

at line 578 deny()

at line 593 bool isApproved()

Return Value

at line 603 int getAuthorUserID()

Return Value

at line 613 string getAuthorName()

Return Value

at line 630 int getApproverUserID()

Return Value

at line 640 string getApproverName()

Return Value

at line 657 int getFullSize()

Return Value

at line 669 string getSize()

Return Value

Examples

at line 681 updateTitle(string $title)

Parameters

at line 696 null|string getTitle()

Return Value

at line 706 updateDescription(string $descr)

at line 1298
`CategoryInterface getObjectAttributeCategory()`

at line 1385
`AttributeValueInterface|null getAttributeValueObject(AttributeKeyInterface|string $ak, bool $createIfNotExists = false)`

in ObjectTrait at line 24
`getAttribute($ak, $mode = false)`

in ObjectTrait at line 36
`Value getAttributeValue($ak)`

in ObjectTrait at line 48
`clearAttribute($ak, bool $doReindexImmediately = true)`

in ObjectTrait at line 72
`Value setAttribute($ak, mixed $value, bool $doReindexImmediately = true)`

at line 292
`__construct()`

at line 316
`static Version add(File $file, string $filename, string $prefix, array $data = [])`

at line 370
`static string cleanTags(string $tagsStr)`

at line 389
`setFile(File $file)`

at line 399
`File getFile()`

at line 409
`int getFileID()`

at line 419
`string getFileUUID()`

at line 428
`bool hasFileUUID()`

at line 438
`setFileVersionID(int $fvID)`

at line 448
`int getFileVersionID()`

at line 458
`rename(string $filename)`

at line 489
`updateFile(string $filename, string $prefix)`

at line 502
`setFilename(string $filename)`

at line 512
`string getFileName()`

at line 522
`string getPrefix()`

at line 532
`DateTime getDateAdded()`

at line 542
`DateTime|null getActivateDateTime()`

at line 551
`approve()`

at line 578
`deny()`

at line 593
`bool isApproved()`

at line 603
`int getAuthorUserID()`

at line 613
`string getAuthorName()`

at line 630
`int getApproverUserID()`

at line 640
`string getApproverName()`

at line 657
`int getFullSize()`

at line 669
`string getSize()`

at line 681
`updateTitle(string $title)`

at line 696
`null|string getTitle()`

at line 706
`updateDescription(string $descr)`

at line 721
`null|string getDescription()`

at line 731
`null|string getExtension()`

at line 741
`updateTags(string $tags)`

at line 757
`string[] getTagsList()`

at line 776
`null|string getTags()`

at line 786
`string|false getMimeType()`

at line 803
`Type getTypeObject()`

at line 818
`string getType()`

at line 830
`string getDisplayType()`

at line 842
`string getGenericTypeText($includeExtension = false)`

at line 869
`logVersionUpdate(int $updateTypeID, int $updateTypeAttributeID = 0)`

at line 889
`string[] getVersionLogComments()`

at line 942
`string|null getRelativePath()`

at line 971
`string|null getURL()`

at line 992
`protected ConfigurationInterface|null getFileStorageLocationConfiguration()`

at line 1007
`bool hasPublicURL()`

at line 1023
`URLInterface getDownloadURL()`

at line 1042
`URLInterface getForceDownloadURL()`

at line 1061
`Response buildForceDownloadResponse()`

at line 1078
`bool canView()`

at line 1090
`bool canEdit()`

at line 1103
`Version duplicate()`

at line 1142
`duplicateUnderlyingFile()`

at line 1171
`delete(bool $deleteFilesAndThumbnails = false)`

at line 1228
`File getFileResource()`

at line 1244
`updateContents(string $contents, bool $rescanThumbnails = true)`

at line 1272
`string|null getFileContents()`

at line 1313
`null|int refreshAttributes(bool $rescanThumbnails = true)`

at line 1373
`FileValue[] getAttributes()`

at line 1409
`ImageInterface|null getImagineImage()`

at line 1459
`bool hasImagineImage()`

at line 1467
`releaseImagineImage()`

at line 1483
`bool refreshThumbnails(bool $deleteExistingThumbnails)`