Menu

## Upload extends Ext
in package

Upload.php : 79

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() : 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

Upload.php : 89

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

Upload.php : 92

Database value option (`Db()`) - Content type

`public mixed DB_CONTENT_TYPE = 'editor-contentType'`

#### DB_EXTN

Upload.php : 95

Database value option (`Db()`) - File extension

`public mixed DB_EXTN = 'editor-extn'`

#### DB_FILE_NAME

Upload.php : 98

Database value option (`Db()`) - File name (with extension)

`public mixed DB_FILE_NAME = 'editor-fileName'`

#### DB_FILE_SIZE

Upload.php : 101

Database value option (`Db()`) - File size (bytes)

`public mixed DB_FILE_SIZE = 'editor-fileSize'`

#### DB_MIME_TYPE

Upload.php : 104

Database value option (`Db()`) - MIME type

`public mixed DB_MIME_TYPE = 'editor-mimeType'`

#### DB_READ_ONLY

Upload.php : 118

Read from the database - don't write to it

`public mixed DB_READ_ONLY = 'editor-readOnly'`

#### DB_SYSTEM_PATH

Upload.php : 107

Database value option (`Db()`) - Full system path to the file

`public mixed DB_SYSTEM_PATH = 'editor-systemPath'`

#### DB_WEB_PATH

Upload.php : 114

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.php : 149

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

Upload.php : 179

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

Upload.php : 201

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

Upload.php : 231

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 ]) : 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 : mixed = null

##### Return values

self —

Current instance, used for chaining

#### dbClean()

Upload.php : 253

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

Ext.php : 51

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!

##### Return values

Editor|Field|Join|Upload —

class @static

#### instantiate()

Ext.php : 32

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.

##### Return values

Editor|Field|Join|Upload —

Instantiated class @static

#### mode()

Upload.php : 272

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

Upload.php : 289

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

Upload.php : 306

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

Ext.php : 75

Common getter / setter function for DataTables classes.

`protected _getSet(mixed &$prop, mixed $val[, mixed $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 @param mixed $val The value to set - if given as null, then we assume that the function is being used as a getter. @param boolean $array 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 self|mixed Class instance if setting (allowing chaining), or the value requested if getting.

$val : mixed
$array : mixed = false

##### Return values

mixed —

#### _propExists()

Ext.php : 105

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

Ext.php : 142

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

Ext.php : 186

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

throws
  Exception

  Information about duplicate properties

private

##### Return values

mixed —

## Search results