SilverStripe\Assets\File

This class handles the representation of a file on the filesystem within the framework.

Most of the methods also handle the subclass.
Note: The files are stored in the assets/ directory, but SilverStripe
looks at the db object to gather information about a file such as URL
It then uses this for all processing functions (like image manipulation).
Security
Caution: It is recommended to disable any script execution in the "assets/"
directory in the webserver configuration, to reduce the risk of exploits.
See http://doc.silverstripe.org/secure-development#filesystem
Asset storage
As asset storage is configured separately to any File DataObject records, this class
does not make any assumptions about how these records are saved. They could be on
a local filesystem, remote filesystem, or a virtual record container (such as in local memory).
The File dataobject simply represents an externally facing view of shared resources
within this asset store.
Internally individual files are referenced by a"Filename" parameter, which represents a File, extension,
and is optionally prefixed by a list of custom directories. This path is root-agnostic, so it does not
automatically have a direct url mapping (even to the site's base directory).
Additionally, individual files may have several versions distinguished by sha1 hash,
of which a File DataObject can point to a single one. Files can also be distinguished by
variants, which may be resized images or format-shifted documents.
Properties
- "Title": Optional title of the file (for display purposes only).
Defaults to "Name". Note that the Title field of Folder (subclass of File)
is linked to Name, so Name and Title will always be the same.
-"File": Physical asset backing this DB record. This is a composite DB field with
its own list of properties. for more information
- "Content": Typically unused, but handy for a textual representation of
files, e.g. for fulltext indexing of PDF documents.
- "ParentID": Points to a record. Should be in sync with
"Filename". A ParentID=0 value points to the "assets/" folder, not the webroot.
-"ShowInSearch": True if this file is searchable

Synopsis

class File extends DataObject implements AssetContainer,Thumbnail,CMSPreviewable,PermissionProvider,Resettable {

// constants
const EDIT_ALL = 'FILE_EDIT_ALL';

// members
private static string $default_sort = "\"Name\"";
private static string $singular_name = "File";
private static string $plural_name = "Files";
private static array $non_live_permissions = ;
private static array $db = ;
private static array $has_one = ;
private static array $has_many = ;
private static array $owned_by = ;
private static array $indexes = ;
private static array $defaults = ;
private static array $extensions = ;
private static array $casting = ;
private static string $table_name = 'File';
private static array $allowed_extensions = ;
private static array $app_categories = ;
private static array $class_for_file_extension = ;
private static bool $apply_restrictions_to_admin = true;
private static boolean $update_filesystem = true;
private static array $file_types = ;
private static array $has_restricted_permissions_cache = ;

// methods
public static void get_shortcodes()
public bool exists()
public static File|null find()
public string Link()
public void RelativeLink()
public string AbsoluteLink()
public string getTreeTitle()
public bool canView()
public boolean canEdit()
public boolean canCreate()
public boolean canDelete()
public bool hasRestrictedAccess()
private bool hasRestrictedPermissions()
public bool isTrackedFormUpload()
public FieldList getCMSFields()
public string getStatusTitle()
public static string get_app_category()
public static array get_category_extensions()
public string appCategory()
public void onAfterUpload()
protected void onBeforeWrite()
protected void onAfterDelete()
public void onAfterRevertToLive()
protected void updateDependantObjects()
public bool updateFilesystem()
public true|null collateDescendants()
protected AssetNameGenerator getNameGenerator()
public string getAbsoluteURL()
public string getURL()
public string getSourceURL()
public string generateFilename()
public string renameFile()
public void copyFile()
public $this setFilename()
public string getExtension()
public static string get_file_extension()
public static string get_icon_for_extension()
public string getFileType()
public static string get_file_type()
public string|false getSize()
public static string format_size()
public static int ini2bytes()
public int getAbsoluteSize()
public ValidationResult validate()
public static String get_class_for_file_extension()
public static void set_class_for_file_extension()
public void getMetaData()
public void getMimeType()
public void getStream()
public void getString()
public void setFromLocalFile()
public void setFromStream()
public void setFromString()
public void getIsImage()
public void getFilename()
public void getHash()
public void getVariant()
public string forTemplate()
public string getTag()
public void BackLinkTracking()
public int BackLinkTrackingCount()
public static string join_paths()
public void deleteFile()
public void getVisibility()
public void publishFile()
public void protectFile()
public void grantFile()
public void revokeFile()
public void canViewFile()
public void CMSEditLink()
public void PreviewLink()
public PermissionChecker getPermissionChecker()
public void providePermissions()
public static array getAllowedExtensions()
protected string filterFilename()
public void flushCache()
public static void reset()
protected FileNameFilter getFilter()

// Inherited methods from ImageManipulation
public $this setAllowGeneration()
public bool getAllowGeneration()
public DBFile existingOnly()
public abstract string getString()
public abstract resource getStream()
public abstract string getURL()
public abstract string getAbsoluteURL()
public abstract array|null getMetaData()
public abstract string getMimeType()
public abstract int getAbsoluteSize()
public abstract bool exists()
public abstract string getFilename()
public abstract string getHash()
public abstract string getVariant()
public abstract bool getIsImage()
public AssetContainer Pad()
public AssetContainer Resampled()
public void updateURL()
public AssetContainer ResizedImage()
public AssetContainer Fit()
public AssetContainer FitMax()
public AssetContainer ScaleWidth()
public AssetContainer ScaleMaxWidth()
public AssetContainer ScaleHeight()
public AssetContainer ScaleMaxHeight()
public AssetContainer CropWidth()
public AssetContainer CropHeight()
public AssetContainer FillMax()
public AssetContainer Fill()
public AssetContainer Quality()
public DBFile|DBHTMLText CMSThumbnail()
public AssetContainer|DBHTMLText StripThumbnail()
public AssetContainer|DBHTMLText PreviewThumbnail()
public AssetContainer Thumbnail()
public AssetContainer|DBHTMLText ThumbnailIcon()
public DBHTMLText IconTag()
public string ThumbnailURL()
public string getIcon()
public Image_Backend getImageBackend()
public $this setImageBackend()
public int getWidth()
public int getHeight()
public int getOrientation()
public boolean isSize()
public boolean isWidth()
public boolean isHeight()
public DBFile manipulateImage()
public DBFile manipulate()
public string variantName()
public array|null variantParts()
protected int castDimension()
public AssetContainer setAttribute()
public void initAttributes()
protected void getDefaultAttributes()
public array getAttributes()
public bool IsLazyLoaded()
public AssetContainer LazyLoad()

}

Hierarchy

Extends

SilverStripe\ORM\DataObject

Uses

SilverStripe\Assets\ImageManipulation

Implements

SilverStripe\Assets\Storage\AssetContainer
SilverStripe\Assets\Thumbnail
SilverStripe\ORM\CMSPreviewable
SilverStripe\Security\PermissionProvider
SilverStripe\Core\Resettable

Tasks

Line	Task
1295	- Implement PolymorphicManyManyList to replace this

Constants

Name	Value
EDIT_ALL	'FILE_EDIT_ALL'

Members

private

$allowed_extensions — array
$app_categories — array
$apply_restrictions_to_admin — SilverStripe\Assets\bool
$casting
$class_for_file_extension —
Map of file extensions to class type
$db
$default_sort
$defaults
$extensions
$file_types — array
A list of file extensions and a description of what type of file they represent
$has_many
$has_one
$has_restricted_permissions_cache
$indexes
$non_live_permissions — array
Anyone with CMS access can view draft files
$owned_by
$plural_name
$singular_name — string
$table_name
$update_filesystem — boolean

protected

$allowGeneration — SilverStripe\Assets\bool
If image resizes are allowed
$imageBackend — SilverStripe\Assets\Image_Backend

Methods

private

hasRestrictedPermissions() — Recursively determine whether a File has, or inherits, restricted permissions.

protected

filterFilename() — Pass name through standard FileNameFilter
getFilter()
getNameGenerator() — Get an asset renamer for the given filename.
onAfterDelete() — Update link tracking on delete
onBeforeWrite() — Make sure the file has a name
updateDependantObjects() — Update objects linking to this file

public

AbsoluteLink() — Just an alias function to keep a consistent API with SiteTree
BackLinkTracking() — Get the back-link tracking objects that link to this file via HTML fields
BackLinkTrackingCount() — Count of backlinks Note: Doesn't filter broken records
CMSEditLink()
Link() — Just an alias function to keep a consistent API with SiteTree
PreviewLink()
RelativeLink()
appCategory() — Returns a category based on the file extension.
canCreate() — Check if a file can be created
canDelete() — Check if this file can be deleted
canEdit() — Check if this file can be modified
canView()
canViewFile()
collateDescendants() — Collate selected descendants of this page.
copyFile()
deleteFile()
exists() — A file only exists if the file_exists() and is in the DB as a record
find() — Find a File object by the given filename.
flushCache()
forTemplate() — Return a html5 tag of the appropriate for this file (normally img or a)
format_size() — Formats a file size (eg: (int)42 becomes string '42 bytes')
generateFilename() — Get expected value of Filename tuple value. Will be used to trigger a file move on draft stage.
getAbsoluteSize() — Return file size in bytes.
getAbsoluteURL() — Gets the URL of this file
getAllowedExtensions() — Get the list of globally allowed file extensions for file uploads.
getCMSFields() — List of basic content editable file fields.
getExtension() — Returns the file extension
getFileType() — Return the type of file for the given extension on the current file name.
getFilename()
getHash()
getIsImage()
getMetaData()
getMimeType()
getPermissionChecker()
getSize() — Returns the size of the file type in an appropriate format.
getSourceURL() — Get URL, but without resampling.
getStatusTitle() — Get title for current file status
getStream()
getString()
getTag() — Return a html5 tag of the appropriate for this file (normally img or a)
getTreeTitle()
getURL() — Gets the URL of this file
getVariant()
getVisibility()
get_app_category() — Returns a category based on the file extension.
get_category_extensions() — For a category or list of categories, get the list of file extensions
get_class_for_file_extension() — Maps a {@link File} subclass to a specific extension.
get_file_extension() — Gets the extension of a filepath or filename, by stripping away everything before the last "dot".
get_file_type() — Get descriptive type of file based on filename
get_icon_for_extension() — Given an extension, determine the icon that should be used
get_shortcodes()
grantFile()
hasRestrictedAccess() — Check if the File has a CanViewType set or inherited at "LoggedInUsers or above"
ini2bytes() — Convert a php.ini value (eg: 512M) to bytes
isTrackedFormUpload() — If the file was uploaded via a form and tracked in the database
join_paths() — Joins one or more segments together to build a Filename identifier.
onAfterRevertToLive()
onAfterUpload() — Should be called after the file was uploaded
protectFile()
providePermissions() — Return a map of permission codes to add to the dropdown shown in the Security section of the CMS.
publishFile()
renameFile() — Rename this file.
reset()
revokeFile()
setFilename() — Update the ParentID and Name for the given filename.
setFromLocalFile()
setFromStream()
setFromString()
set_class_for_file_extension() — See {@link get_class_for_file_extension()}.
updateFilesystem() — This will check if the parent record and/or name do not match the name on the underlying DBFile record, and if so, copy this file to the new location, and update the record to point to this new file.
validate()

Inherited from SilverStripe\Assets\ImageManipulation

protected

castDimension() — Validate a width or size is valid and casts it to integer
getDefaultAttributes()

public

CMSThumbnail() — Default CMS thumbnail
CropHeight() — Crop image on Y axis if it exceeds specified height. Retain width.
CropWidth() — Crop image on X axis if it exceeds specified width. Retain height.
Fill() — Resize and crop image to fill specified dimensions.
FillMax() — Crop this image to the aspect ratio defined by the specified width and height, then scale down the image to those dimensions if it exceeds them.
Fit() — Scale image proportionally to fit within the specified bounds
FitMax() — Proportionally scale down this image if it is wider or taller than the specified dimensions.
IconTag() — Get HTML for img containing the icon for this file
IsLazyLoaded() — Determine whether the image should be lazy loaded
LazyLoad() — Set the lazy loading state for this Image
Pad() — Fit image to specified dimensions and fill leftover space with a solid colour (default white). Use in templates with $Pad.
PreviewThumbnail() — Get preview for this file
Quality() — Set the quality of the resampled image
Resampled() — Forces the image to be resampled, if possible
ResizedImage() — Generate a resized copy of this image with the given width & height.
ScaleHeight() — Scale image proportionally by height. Use in templates with $ScaleHeight.
ScaleMaxHeight() — Proportionally scale down this image if it is taller than the specified height.
ScaleMaxWidth() — Proportionally scale down this image if it is wider than the specified width.
ScaleWidth() — Scale image proportionally by width. Use in templates with $ScaleWidth.
StripThumbnail() — Generates a thumbnail for use in the gridfield view
Thumbnail() — Default thumbnail generation for Images
ThumbnailIcon() — Thubnail generation for all file types.
ThumbnailURL() — Get URL to thumbnail of the given size.
existingOnly() — Return clone of self which promises to only return existing thumbnails
exists() — Determine if this container has a valid value
getAbsoluteSize() — Return file size in bytes.
getAbsoluteURL()
getAllowGeneration() — Check if resizes are allowed
getAttributes() — Allows customization through an 'updateAttributes' hook on the base class.
getFilename() — Get value of filename
getHash() — Get value of hash
getHeight() — Get the height of this image.
getIcon() — Return the relative URL of an icon for the file type, based on the {@link appCategory()} value.
getImageBackend() — Get Image_Backend instance for this image
getIsImage() — Determine if a valid non-empty image exists behind this asset
getMetaData() — Get metadata for this file
getMimeType() — Get mime type
getOrientation() — Get the orientation of this image.
getStream()
getString()
getURL()
getVariant() — Get value of variant
getWidth() — Get the width of this image.
initAttributes() — Initialise the attirbutes on this object. Should only be called imiditely after intialising the object.
isHeight() — Determine if this image is of the specified width
isSize() — Determine if this image is of the specified size
isWidth() — Determine if this image is of the specified width
manipulate() — Generate a new DBFile instance using the given callback if it hasn't been created yet, or return the existing one if it has.
manipulateImage() — Wrapper for manipulate that passes in and stores Image_Backend objects instead of tuples
setAllowGeneration() — Set whether image resizes are allowed
setAttribute() — Add a HTML attribute when rendering this object. This method is immutable, it will return you a copy of the original object.
setImageBackend()
updateURL() — Update the url to point to a resampled version if forcing
variantName() — Name a variant based on a format with arbitrary parameters
variantParts() — Reverses {@link variantName()}.