Editor PHP 2.2.2

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
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" )
		)

Table of Contents

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.
__construct()  : mixed
Upload instance constructor.
action()  : self
Set the action to take when a file is uploaded. This can be either of:.
allowedExtensions()  : self
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()  : self
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()  : self
Set a callback function that is used to remove files which no longer have a reference in a source table.
inst()  : Editor|Field|Join|Upload
Static method to instantiate a new instance of a class (shorthand of 'instantiate').
instantiate()  : Editor|Field|Join|Upload
Static method to instantiate a new instance of a class.
mode()  : mixed
Set the permissions on the file after it has been uploaded using chmod.
validator()  : self
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()  : self
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()  : self|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([string|callable $action = null ]) : mixed
Parameters
$action : string|callable = null

Action to take on upload - this is applied directly to Upload->action().

Return values
mixed —

action()

Set the action to take when a file is uploaded. This can be either of:.

public action(string|callable $action) : self
  • 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 : string|callable

Action to take - see description above.

Return values
self —

Current instance, used for chaining

allowedExtensions()

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' ]) : self
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
deprecated

Use Validate::fileExtensions

Return values
self —

Current instance, used for chaining

db()

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[, callable $format = null ]) : self
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 : callable = null

Formatting function that can change the data obtained from the database. Only gets a single parameter passed in - the database row for the file that is read.

Return values
self —

Current instance, used for chaining

dbClean()

Set a callback function that is used to remove files which no longer have a reference in a source table.

public dbClean(mixed $tableField[, callable $callback = null ]) : self
Parameters
$tableField : mixed
$callback : callable = null

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.

Return values
self —

Current instance, used for chaining

inst()

Static method to instantiate a new instance of a class (shorthand of 'instantiate').

public static inst() : Editor|Field|Join|Upload

This method performs exactly the same actions as the 'instantiate' static method, but is simply shorter and easier to type!

Tags
static
Return values
Editor|Field|Join|Upload —

class

instantiate()

Static method to instantiate a new instance of a class.

public static instantiate() : Editor|Field|Join|Upload

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.

Tags
static
Return values
Editor|Field|Join|Upload —

Instantiated class

mode()

Set the permissions on the file after it has been uploaded using chmod.

public mode(mixed $m) : mixed
Parameters
$m : mixed
Return values
mixed —

validator()

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(callable $fn) : self
Parameters
$fn : callable

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).

Return values
self —

Current instance, used for chaining

where()

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(callable $fn) : self
Parameters
$fn : callable

Where function.

Return values
self —

Current instance, used for chaining

_getSet()

Common getter / setter function for DataTables classes.

protected _getSet(mixed &$prop, mixed $val[, bool $array = false ]) : self|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.

Return values
self|mixed —

Class instance if setting (allowing chaining), or the value requested if getting.

_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

Tags
private
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

Tags
private
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

Tags
private
Return values
mixed — 

        

        
    




    

    

                

    

        

            
Search results