Editor PHP 2.3.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.

	new Field( 'imageId' )
		->upload(
			new Upload( $_SERVER['DOCUMENT_ROOT'].'/uploads/__ID__.__EXTN__' )
		 		->db( 'files', 'id', [
					'webPath'     => Upload::DB_WEB_PATH,
					'fileName'    => Upload::DB_FILE_NAME,
					'fileSize'    => Upload::DB_FILE_SIZE,
					'systemPath'  => Upload::DB_SYSTEM_PATH
				] )
				->allowedExtensions( [ 'png', 'jpg' ], "Please upload an image file" )
		)

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
$this

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

Use Validate::fileExtensions

Return values
$this

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[, 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
$this

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[, mixed $callback = null ]) : $this
Parameters
$tableField : mixed
$callback : mixed = null
Return values
$this

inst()

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
$this

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(mixed $fn) : $this
Parameters
$fn : mixed
Return values
$this

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


        
On this page

Search results