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).
<b>Security</b>
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
<b>Asset storage</b>
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.
<b>Properties</b>
- "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
- // 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
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()}.