1. class
  2. Concrete
  3. \
  4. Core
  5. \
  6. Entity
  7. \
  8. File
  9. \
  10. Version

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)

No description

from  ObjectTrait
Value
setAttribute($ak, mixed $value)

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.

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

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

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 1206
CategoryInterface getObjectAttributeCategory()

No description

Return Value

CategoryInterface

See also

ObjectInterface::getObjectAttributeCategory

at line 1293
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

See also

ObjectInterface::getAttributeValueObject

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

No description

Parameters

$ak
$mode

in ObjectTrait at line 36
Value getAttributeValue($ak)

No description

Parameters

$ak

Return Value

Value

in ObjectTrait at line 47
clearAttribute($ak)

No description

Parameters

$ak

in ObjectTrait at line 68
Value setAttribute($ak, mixed $value)

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

Parameters

$ak
mixed $value

Return Value

Value

at line 282
__construct()

Initialize the instance.

at line 306
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 359
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 378
setFile(File $file)

Set the associated File instance.

Parameters

File $file

at line 388
File getFile()

Get the associated File instance.

Return Value

File

at line 398
int getFileID()

Get the ID of the associated file instance.

Return Value

int

at line 408
setFileVersionID(int $fvID)

Set the progressive file version identifier.

Parameters

int $fvID

at line 418
int getFileVersionID()

Get the progressive file version identifier.

Return Value

int

at line 428
rename(string $filename)

Rename the file.

Parameters

string $filename

at line 459
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 472
setFilename(string $filename)

Set the name of the file.

Parameters

string $filename

at line 482
string getFileName()

Get the name of the file.

Return Value

string

at line 492
string getPrefix()

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

Return Value

string

at line 502
DateTime getDateAdded()

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

Return Value

DateTime

at line 512
DateTime|null getActivateDateTime()

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

Return Value

DateTime|null

at line 521
approve()

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

The currently logged in user (if any) will be stored as the approver.

at line 550
deny()

Mark this file version as not approved.

at line 565
bool isApproved()

Is this version the approved one for the associated file?

Return Value

bool

at line 575
int getAuthorUserID()

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

Return Value

int

at line 585
string getAuthorName()

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

Return Value

string

at line 602
int getApproverUserID()

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

Return Value

int

at line 612
string getApproverName()

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

Return Value

string

at line 629
int getFullSize()

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

Return Value

int

at line 641
string getSize()

Get the formatted file size.

Return Value

string

Examples

123 KB

at line 653
updateTitle(string $title)

Update the title of the file.

Parameters

string $title

at line 668
null|string getTitle()

Get the title of the file version.

Return Value

null|string

at line 678
updateDescription(string $descr)

Update the description of the file.

Parameters

string $descr

at line 693
null|string getDescription()

Get the description of the file version.

Return Value

null|string

at line 703
null|string getExtension()

Get the extension of the file version.

Return Value

null|string

at line 713
updateTags(string $tags)

Update the tags associated to the file.

Parameters

string $tags

List of tags separated by newlines and/or commas

at line 729
string[] getTagsList()

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

Return Value

string[]

at line 748
null|string getTags()

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

Return Value

null|string

at line 758
string|false getMimeType()

Get the mime type of the file if known.

Return Value

string|false

at line 775
Type getTypeObject()

Get the type of the file.

Return Value

Type

at line 790
string getType()

Get the name of the file type.

Return Value

string

at line 802
string getDisplayType()

Get the localized name of the file type.

Return Value

string

at line 814
string getGenericTypeText()

Get the localized name of the generic category type.

Return Value

string

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

Log updates to files.

Parameters

int $updateTypeID

One of the Version::UT_... constants
int $updateTypeAttributeID

the ID of the attribute that has been updated (if any - useful when $updateTypeID is UT_EXTENDED_ATTRIBUTE)

at line 847
string[] getVersionLogComments()

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

Return Value

string[]

at line 900
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 929
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).

Return NULL if the file storage location is invalid. If the file is not directly accessible, you'll get the download URL.

Return Value

string|null

at line 954
URLInterface getDownloadURL()

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

This passes through the download_file single page.

Return Value

URLInterface

at line 969
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).

Return Value

URLInterface

at line 984
Response buildForceDownloadResponse()

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

Return Value

Response

at line 1002
bool canView()

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

Return Value

bool

at line 1014
bool canEdit()

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

Return Value

bool

at line 1027
Version duplicate()

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

The new Version instance will have the current user as the author (if available), and a new version ID.

Return Value

Version

at line 1068
duplicateUnderlyingFile()

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

at line 1098
delete(bool $deleteFilesAndThumbnails = false)

Delete this version of the file.

Parameters

bool $deleteFilesAndThumbnails

should we delete the actual file and the thumbnails?

at line 1136
File getFileResource()

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

Return Value

File

Exceptions

FileNotFoundException

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

Update the contents of the file.

Parameters

string $contents

The new content of the file
bool $rescanThumbnails

Should thumbnails be rescanned as well?

at line 1180
string|null getFileContents()

Get the contents of the file.

Return Value

string|null

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

at line 1221
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 1281
FileValue[] getAttributes()

Get the list of attributes associated to this file version.

Return Value

FileValue[]

at line 1317
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 1367
bool hasImagineImage()

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

Return Value

bool

at line 1375
releaseImagineImage()

Unload the loaded Image instance.

at line 1387
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 1438
generateThumbnail(Version $type)

Generate a thumbnail for a specific thumbnail type version.

Parameters

Version $type

at line 1527
importThumbnail(Version $version, string $path)

Import an existing file as a thumbnail type version.

Parameters

Version $version
string $path

at line 1575
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 1607
Thumbnail[] getThumbnails()

Get the list of all the thumbnails.

Return Value

Thumbnail[]

Exceptions

InvalidDimensionException

at line 1638
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 1661
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 1684
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 1719
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 1742
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 1766
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 1799
forceDownload() deprecated

deprecated Use buildForceDownloadResponse

No description

at line 1819
bool hasThumbnail(int $level) deprecated

deprecated

No description

Parameters

int $level

Return Value

bool

at line 1836
bool rescanThumbnails() deprecated

deprecated use refreshThumbnails(true) instead

No description

Return Value

bool

at line 1846
protected save(bool $flush = true)

Save the instance changes.

Parameters

bool $flush

Flush the EM cache?