Upload
extends Ext
in package
Upload class for Editor. This class provides the ability to easily specify file upload information, specifically how the file should be recorded on the server (database and file system).
An instance of this class is attached to a field using the Field->upload() method. When Editor detects a file upload for that file the information provided for this instance is executed.
The configuration is primarily driven through the Upload->db() and Upload->action() methods:
- Upload->db() Describes how information about the uploaded file is to be stored on the database.
- Upload->action() Describes where the file should be stored on the file system and provides the option of specifying a custom action when a file is uploaded.
Both methods are optional - you can store the file on the server using the Upload->db() method only if you want to store the file in the database, or if you don't want to store relational data on the database us only Upload->action(). However, the majority of the time it is best to use both - store information about the file on the database for fast retrieval (using a Editor->leftJoin() for example) and the file on the file system for direct web access.
Tags
Table of Contents
Constants
- DB_CONTENT = 'editor-content'
- Database value option (`Db()`) - File content. This should be written to a blob. Typically this should be avoided and the file saved on the file system, but there are cases where it can be useful to store the file in the database.
- DB_CONTENT_TYPE = 'editor-contentType'
- Database value option (`Db()`) - Content type
- DB_EXTN = 'editor-extn'
- Database value option (`Db()`) - File extension
- DB_FILE_NAME = 'editor-fileName'
- Database value option (`Db()`) - File name (with extension)
- DB_FILE_SIZE = 'editor-fileSize'
- Database value option (`Db()`) - File size (bytes)
- DB_MIME_TYPE = 'editor-mimeType'
- Database value option (`Db()`) - MIME type
- DB_READ_ONLY = 'editor-readOnly'
- Read from the database - don't write to it.
- DB_SYSTEM_PATH = 'editor-systemPath'
- Database value option (`Db()`) - Full system path to the file
- DB_WEB_PATH = 'editor-webPath'
- Database value option (`Db()`) - HTTP path to the file. This is derived from the system path by removing `$_SERVER['DOCUMENT_ROOT']`. If your images live outside of the document root a custom value would be to be used.
Methods
- __construct() : mixed
- Upload instance constructor.
- action() : $this
- Set the action to take when a file is uploaded. This can be either of:.
- allowedExtensions() : $this
- An array of valid file extensions that can be uploaded. This is for simple validation that the file is of the expected type - for example you might use `[ 'png', 'jpg', 'jpeg', 'gif' ]` for images. The check is case-insensitive. If no extensions are given, no validation is performed on the file extension.
- db() : $this
- Database configuration method. When used, this method will tell Editor what information you want written to a database on file upload, should you wish to store relational information about your file on the database (this is generally recommended).
- dbClean() : $this
- Set a callback function that is used to remove files which no longer have a reference in a source table.
- inst() : static
- Static method to instantiate a new instance of a class (shorthand of 'instantiate').
- instantiate() : static
- Static method to instantiate a new instance of a class.
- mode() : $this
- Set the permissions on the file after it has been uploaded using chmod.
- validator() : $this
- Add a validation method to check file uploads. Multiple validators can be added by calling this method multiple times - they will be executed in sequence when a file has been uploaded.
- where() : $this
- Add a condition to the data to be retrieved from the database. This must be given as a function to be executed (usually anonymous) and will be passed in a single argument, the `Query` object, to which conditions can be added. Multiple calls to this method can be made.
- _getSet() : mixed
- Common getter / setter function for DataTables classes.
- _propExists() : bool
- Determine if a property is available in a data set (allowing `null` to be a valid value).
- _readProp() : mixed
- Read a value from a data structure, using Javascript dotted object notation. This is the inverse of the `_writeProp` method and provides the same support, matching DataTables' ability to read nested JSON data objects.
- _writeProp() : mixed
- Write the field's value to an array structure, using Javascript dotted object notation to indicate JSON data structure. For example `name.first` gives the data structure: `name: { first: ... }`. This matches DataTables own ability to do this on the client-side, although this doesn't implement implement quite such a complex structure (no array / function support).
Constants
DB_CONTENT
Database value option (`Db()`) - File content. This should be written to a blob. Typically this should be avoided and the file saved on the file system, but there are cases where it can be useful to store the file in the database.
public
mixed
DB_CONTENT
= 'editor-content'
DB_CONTENT_TYPE
Database value option (`Db()`) - Content type
public
mixed
DB_CONTENT_TYPE
= 'editor-contentType'
DB_EXTN
Database value option (`Db()`) - File extension
public
mixed
DB_EXTN
= 'editor-extn'
DB_FILE_NAME
Database value option (`Db()`) - File name (with extension)
public
mixed
DB_FILE_NAME
= 'editor-fileName'
DB_FILE_SIZE
Database value option (`Db()`) - File size (bytes)
public
mixed
DB_FILE_SIZE
= 'editor-fileSize'
DB_MIME_TYPE
Database value option (`Db()`) - MIME type
public
mixed
DB_MIME_TYPE
= 'editor-mimeType'
DB_READ_ONLY
Read from the database - don't write to it.
public
mixed
DB_READ_ONLY
= 'editor-readOnly'
DB_SYSTEM_PATH
Database value option (`Db()`) - Full system path to the file
public
mixed
DB_SYSTEM_PATH
= 'editor-systemPath'
DB_WEB_PATH
Database value option (`Db()`) - HTTP path to the file. This is derived from the system path by removing `$_SERVER['DOCUMENT_ROOT']`. If your images live outside of the document root a custom value would be to be used.
public
mixed
DB_WEB_PATH
= 'editor-webPath'
Methods
__construct()
Upload instance constructor.
public
__construct([mixed $action = null ]) : mixed
Parameters
- $action : mixed = null
action()
Set the action to take when a file is uploaded. This can be either of:.
public
action(mixed $action) : $this
- A string - the value given is the full system path to where the
uploaded file is written to. The value given can include three "macros"
which are replaced by the script dependent on the uploaded file:
-
__EXTN__
- the file extension -
__NAME__
- the uploaded file's name (including the extension) -
__ID__
- Database primary key value if the Upload->db() method is used.
-
- A closure - if a function is given the responsibility of what to do with the uploaded file is transferred to this function. That will typically involve writing it to the file system so it can be used later.
Parameters
- $action : mixed
Return values
$thisallowedExtensions()
An array of valid file extensions that can be uploaded. This is for simple validation that the file is of the expected type - for example you might use `[ 'png', 'jpg', 'jpeg', 'gif' ]` for images. The check is case-insensitive. If no extensions are given, no validation is performed on the file extension.
public
allowedExtensions(array<string|int, string> $extn[, string $error = 'This file type cannot be uploaded' ]) : $this
Parameters
- $extn : array<string|int, string>
-
List of file extensions that are allowable for the upload
- $error : string = 'This file type cannot be uploaded'
-
Error message if a file is uploaded that doesn't match the valid list of extensions.
Tags
Return values
$thisdb()
Database configuration method. When used, this method will tell Editor what information you want written to a database on file upload, should you wish to store relational information about your file on the database (this is generally recommended).
public
db(string $table, string $pkey, array<string|int, mixed> $fields[, mixed $format = null ]) : $this
Parameters
- $table : string
-
The name of the table where the file information should be stored
- $pkey : string
-
Primary key column name. The
Upload
class requires that the database table have a single primary key so each row can be uniquely identified. - $fields : array<string|int, mixed>
-
A list of the fields to be written to on upload. The property names are the database columns and the values can be defined by the constants of this class. The value can also be a string or a closure function if you wish to send custom information to the database.
- $format : mixed = null
Return values
$thisdbClean()
Set a callback function that is used to remove files which no longer have a reference in a source table.
public
dbClean(mixed $tableField[, mixed $callback = null ]) : $this
Parameters
- $tableField : mixed
- $callback : mixed = null
Return values
$thisinst()
Static method to instantiate a new instance of a class (shorthand of 'instantiate').
public
static inst() : static
This method performs exactly the same actions as the 'instantiate' static method, but is simply shorter and easier to type!
Return values
static —class
instantiate()
Static method to instantiate a new instance of a class.
public
static instantiate() : static
A factory method that will create a new instance of the class that has extended 'Ext'. This allows classes to be instantiated and then chained - which otherwise isn't available until PHP 5.4. If using PHP 5.4 or later, simply create a 'new' instance of the target class and chain methods as normal.
Return values
static —Instantiated class
mode()
Set the permissions on the file after it has been uploaded using chmod.
public
mode(mixed $m) : $this
Parameters
- $m : mixed
Return values
$thisvalidator()
Add a validation method to check file uploads. Multiple validators can be added by calling this method multiple times - they will be executed in sequence when a file has been uploaded.
public
validator(mixed $fn) : $this
Parameters
- $fn : mixed
Return values
$thiswhere()
Add a condition to the data to be retrieved from the database. This must be given as a function to be executed (usually anonymous) and will be passed in a single argument, the `Query` object, to which conditions can be added. Multiple calls to this method can be made.
public
where(mixed $fn) : $this
Parameters
- $fn : mixed
Return values
$this_getSet()
Common getter / setter function for DataTables classes.
protected
_getSet(mixed &$prop, mixed $val[, bool $array = false ]) : mixed
This getter / setter method makes building getter / setting methods easier, by abstracting everything to a single function call.
Parameters
- $prop : mixed
-
The property to set
- $val : mixed
-
The value to set - if given as null, then we assume that the function is being used as a getter.
- $array : bool = false
-
Treat the target property as an array or not (default false). If used as an array, then values passed in are added to the $prop array.
_propExists()
Determine if a property is available in a data set (allowing `null` to be a valid value).
protected
_propExists(string $name, array<string|int, mixed> $data) : bool
Parameters
- $name : string
-
Javascript dotted object name to write to
- $data : array<string|int, mixed>
-
Data source array to read from
Return values
bool —true if present, false otherwise
_readProp()
Read a value from a data structure, using Javascript dotted object notation. This is the inverse of the `_writeProp` method and provides the same support, matching DataTables' ability to read nested JSON data objects.
protected
_readProp(string $name, array<string|int, mixed> $data) : mixed
Parameters
- $name : string
-
Javascript dotted object name to write to
- $data : array<string|int, mixed>
-
Data source array to read from
Return values
mixed —The read value, or null if no value found.
_writeProp()
Write the field's value to an array structure, using Javascript dotted object notation to indicate JSON data structure. For example `name.first` gives the data structure: `name: { first: ... }`. This matches DataTables own ability to do this on the client-side, although this doesn't implement implement quite such a complex structure (no array / function support).
protected
_writeProp(array<string|int, mixed> &$out, string $name, mixed $value) : mixed
Parameters
- $out : array<string|int, mixed>
-
Array to write the data to
- $name : string
-
Javascript dotted object name to write to
- $value : mixed
-
Value to write