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:

DataTables\Editor\Upload::db() Describes how information about the uploaded file is to be stored on the database.
DataTables\Editor\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 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 `$action` Action to take on upload - this is applied directly to `DataTables\Editor\Upload::action()`.
`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 `DataTables\Editor\Upload` Current instance, used for chaining
`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 `DataTables\Editor\Upload` Current instance, used for chaining
`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 `DataTables\Editor\Upload` Current instance, used for chaining
`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 `DataTables\Editor\Upload` Current instance, used for chaining
`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 `DataTables\Editor\Upload` Current instance, used for chaining
`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 `$fn` Where function. Returns `DataTables\Editor\Upload` Current instance, used for chaining

Methods inherited from DataTables\Ext
`_getSet(), _propExists(), _readProp(), _writeProp(), inst(), instantiate()`

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.	# `'editor-content'`
`string`	`DB_CONTENT_TYPE` Database value option (`Db()`) - Content type Database value option (`Db()`) - Content type	# `'editor-contentType'`
`string`	`DB_EXTN` Database value option (`Db()`) - File extension Database value option (`Db()`) - File extension	# `'editor-extn'`
`string`	`DB_FILE_NAME` Database value option (`Db()`) - File name (with extension) Database value option (`Db()`) - File name (with extension)	# `'editor-fileName'`
`string`	`DB_FILE_SIZE` Database value option (`Db()`) - File size (bytes) Database value option (`Db()`) - File size (bytes)	# `'editor-fileSize'`
`string`	`DB_MIME_TYPE` Database value option (`Db()`) - MIME type Database value option (`Db()`) - MIME type	# `'editor-mimeType'`
`string`	`DB_SYSTEM_PATH` Database value option (`Db()`) - Full system path to the file Database value option (`Db()`) - Full system path to the file	# `'editor-systemPath'`
`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.	# `'editor-webPath'`
`string`	`DB_READ_ONLY` Read from the database - don't write to it Read from the database - don't write to it	# `'editor-readOnly'`

Namespaces

Classes

Class Upload

Parameters

Parameters

Returns

Deprecated

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns