Class Upload
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 DataTables\Editor\Upload::db()
and DataTables\Editor\Upload::action()
methods:
Both methods are optional - you can store the file on the server using the
DataTables\Editor\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 DataTables\Editor\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.
-
DataTables\Ext
-
DataTables\Editor\Upload
Namespace: DataTables\
Editor
Example:
Store information about a file in a table called files
and the actual
file in an uploads
directory.
Field::inst( 'imageId' )
->upload(
Upload::inst( $_SERVER['DOCUMENT_ROOT'].'/uploads/__ID__.__EXTN__' )
->db( 'files', 'id', array(
'webPath' => Upload::DB_WEB_PATH,
'fileName' => Upload::DB_FILE_NAME,
'fileSize' => Upload::DB_FILE_SIZE,
'systemPath' => Upload::DB_SYSTEM_PATH
) )
->allowedExtensions( array( 'png', 'jpg' ), "Please upload an image file" )
)
Example:
As above, but with PHP 5.4 (which allows chaining from new instances of a
class)
newField( 'imageId' )
->upload(
new Upload( $_SERVER['DOCUMENT_ROOT'].'/uploads/__ID__.__EXTN__' )
->db( 'files', 'id', array(
'webPath' => Upload::DB_WEB_PATH,
'fileName' => Upload::DB_FILE_NAME,
'fileSize' => Upload::DB_FILE_SIZE,
'systemPath' => Upload::DB_SYSTEM_PATH
) )
->allowedExtensions( array( 'png', 'jpg' ), "Please upload an image file" )
)
Located at Editor/Upload.php
Methods summary
public
|
#
__construct( string|callable $action = null )
Upload instance constructor
Upload instance constructor
Parameters
|
public
DataTables\Editor\Upload
|
#
action( string|callable $action )
Set the action to take when a file is uploaded. This can be either of:
Set the action to take when a file is uploaded. This can be either of:
- 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 DataTables\Editor\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
- Action to take - see description above.
Returns
|
public
DataTables\Editor\Upload
|
#
allowedExtensions( string[] $extn, string $error = "This file type cannot be uploaded" )
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.
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.
Deprecated
Use Validate::fileExtensions
Parameters
- $extn
List of file extensions that are allowable for
the upload
- $error
Error message if a file is uploaded that doesn't
match the valid list of extensions.
Returns
|
public
DataTables\Editor\Upload
|
#
db( string $table, string $pkey, array $fields )
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).
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).
Parameters
- $table
The name of the table where the file information
should be stored
- $pkey
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
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.
Returns
|
public
DataTables\Editor\Upload
|
#
dbClean( callable $tableField, $callback = null )
Set a callback function that is used to remove files which no longer have
a reference in a source table.
Set a callback function that is used to remove files which no longer have
a reference in a source table.
Parameters
- $tableField
$callback Function that will be executed on clean. It is
given an array of information from the database about the orphaned
rows, and can return true to indicate that the rows should be
removed from the database. Any other return value (including none)
will result in the records being retained.
- $callback
Returns
|
public
DataTables\Editor\Upload
|
#
validator( callable $fn )
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.
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.
Parameters
- $fn
Validation function. A PHP $_FILES parameter is
passed in for the uploaded file and the return is either a string
(validation failed and error message), or null (validation passed).
Returns
|
public
DataTables\Editor\Upload
|
#
where( callable $fn )
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.
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.
Parameters
Returns
|
Constants summary
string |
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.
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.
|
|
string |
DB_CONTENT_TYPE
Database value option (Db() ) - Content type
Database value option (Db() ) - Content type
|
|
string |
DB_EXTN
Database value option (Db() ) - File extension
Database value option (Db() ) - File extension
|
|
string |
DB_FILE_NAME
Database value option (Db() ) - File name (with extension)
Database value option (Db() ) - File name (with extension)
|
|
string |
DB_FILE_SIZE
Database value option (Db() ) - File size (bytes)
Database value option (Db() ) - File size (bytes)
|
|
string |
DB_MIME_TYPE
Database value option (Db() ) - MIME type
Database value option (Db() ) - MIME type
|
|
string |
DB_SYSTEM_PATH
Database value option (Db() ) - Full system path to the file
Database value option (Db() ) - Full system path to the file
|
|
string |
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.
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.
|
|
string |
DB_READ_ONLY
Read from the database - don't write to it
Read from the database - don't write to it
|
|