Files
safekat/ci4/app/ThirdParty/DatatablesEditor/Editor/Upload.php

736 lines
20 KiB
PHP
Executable File

<?php
/**
* DataTables PHP libraries.
*
* PHP libraries for DataTables and DataTables Editor, utilising PHP 5.3+.
*
* @author SpryMedia
* @copyright 2015 SpryMedia ( http://sprymedia.co.uk )
* @license http://editor.datatables.net/license DataTables Editor
* @link http://editor.datatables.net
*/
namespace DataTables\Editor;
if (!defined('DATATABLES')) exit();
use DataTables;
/**
* 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 {@see
* 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 {@see Upload->db()} and
* {@see Upload->action()} methods:
*
* * {@see Upload->db()} Describes how information about the uploaded file is to be
* stored on the database.
* * {@see 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
* {@see 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
* {@see 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
* {@see Editor->leftJoin()} for example) and the file on the file system for direct
* web access.
*
* @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" )
* )
* ```
*/
class Upload extends DataTables\Ext {
/* * * * * * * * * * * * * * * * * * * * * * * * *
* Constants
*/
/** 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.
*/
const DB_CONTENT = 'editor-content';
/** Database value option (`Db()`) - Content type */
const DB_CONTENT_TYPE = 'editor-contentType';
/** Database value option (`Db()`) - File extension */
const DB_EXTN = 'editor-extn';
/** Database value option (`Db()`) - File name (with extension) */
const DB_FILE_NAME = 'editor-fileName';
/** Database value option (`Db()`) - File size (bytes) */
const DB_FILE_SIZE = 'editor-fileSize';
/** Database value option (`Db()`) - MIME type */
const DB_MIME_TYPE = 'editor-mimeType';
/** Database value option (`Db()`) - Full system path to the file */
const DB_SYSTEM_PATH = 'editor-systemPath';
/** 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.
*/
const DB_WEB_PATH = 'editor-webPath';
/** Read from the database - don't write to it
*/
const DB_READ_ONLY = 'editor-readOnly';
/* * * * * * * * * * * * * * * * * * * * * * * * *
* Private parameters
*/
private $_action = null;
private $_dbCleanCallback = null;
private $_dbCleanTableField = null;
private $_dbTable = null;
private $_dbPKey = null;
private $_dbFields = null;
private $_dbFormat = null;
private $_extns = null;
private $_extnError = null;
private $_error = null;
private $_mode = 0644;
private $_validators = array();
private $_where = array();
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Constructor
*/
/**
* Upload instance constructor
* @param string|callable $action Action to take on upload - this is applied
* directly to {@see Upload->action()}.
*/
function __construct( $action=null )
{
if ( $action ) {
$this->action( $action );
}
}
/* * * * * * * * * * * * * * * * * * * * * * * * *
* Public methods
*/
/**
* 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 {@see 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.
*
* @param string|callable $action Action to take - see description above.
* @return self Current instance, used for chaining
*/
public function action ( $action )
{
$this->_action = $action;
return $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.
*
* @param string[] $extn List of file extensions that are allowable for
* the upload
* @param string $error Error message if a file is uploaded that doesn't
* match the valid list of extensions.
* @return self Current instance, used for chaining
* @deprecated Use Validate::fileExtensions
*/
public function allowedExtensions ( $extn, $error="This file type cannot be uploaded" )
{
$this->_extns = $extn;
$this->_extnError = $error;
return $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).
*
* @param string $table The name of the table where the file information
* should be stored
* @param string $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.
* @param array $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.
* @param callable 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 self Current instance, used for chaining
*/
public function db ( $table, $pkey, $fields, $format=null )
{
$this->_dbTable = $table;
$this->_dbPKey = $pkey;
$this->_dbFields = $fields;
$this->_dbFormat = $format;
return $this;
}
/**
* Set a callback function that is used to remove files which no longer have
* a reference in a source table.
*
* @param callable $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.
* @return self Current instance, used for chaining
*/
public function dbClean( $tableField, $callback=null )
{
// Argument swapping
if ( $callback === null ) {
$callback = $tableField;
$tableField = null;
}
$this->_dbCleanCallback = $callback;
$this->_dbCleanTableField = $tableField;
return $this;
}
/**
* Set the permissions on the file after it has been uploaded using
* chmod.
*/
public function mode( $m ) {
$this->_mode = $m;
return $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.
*
* @param callable $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).
* @return self Current instance, used for chaining
*/
public function validator ( $fn )
{
$this->_validators[] = $fn;
return $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.
*
* @param callable $fn Where function.
* @return self Current instance, used for chaining
*/
public function where ( $fn )
{
$this->_where[] = $fn;
return $this;
}
/* * * * * * * * * * * * * * * * * * * * * * * * *
* Internal methods
*/
/**
* Get database information data from the table
*
* @param \DataTables\Database $db Database
* @param number[] [$ids=null] Limit to a specific set of ids
* @return array Database information
* @internal
*/
public function data ( $db, $ids=null )
{
if ( ! $this->_dbTable ) {
return null;
}
// Select the details requested, for the columns requested
$q = $db
->query( 'select' )
->table( $this->_dbTable )
->get( $this->_dbPKey );
foreach ( $this->_dbFields as $column => $prop ) {
if ( $prop !== self::DB_CONTENT ) {
$q->get( $column );
}
}
if ( $ids !== null ) {
$q->where_in( $this->_dbPKey, $ids );
}
for ( $i=0, $ien=count($this->_where) ; $i<$ien ; $i++ ) {
$q->where( $this->_where[$i] );
}
$result = $q->exec()->fetchAll();
$out = array();
for ( $i=0, $ien=count($result) ; $i<$ien ; $i++ ) {
if ($this->_dbFormat) {
$this->_dbFormat( $result[$i] );
}
$out[ $result[$i][ $this->_dbPKey ] ] = $result[$i];
}
return $out;
}
/**
* Clean the database
* @param \DataTables\Editor $editor Calling Editor instance
* @param Field $field Host field
* @internal
*/
public function dbCleanExec ( $editor, $field )
{
// Database and file system clean up BEFORE adding the new file to
// the db, otherwise it will be removed immediately
$tables = $editor->table();
$this->_dbClean( $editor->db(), $tables[0], $field->dbField() );
}
/**
* Get the set error message
*
* @return string Class error
* @internal
*/
public function error ()
{
return $this->_error;
}
/**
* Execute an upload
*
* @param \DataTables\Editor $editor Calling Editor instance
* @return int Primary key value
* @internal
*/
public function exec ( $editor )
{
$id = null;
$upload = $_FILES['upload'];
// Validation - PHP standard validation
if ( $upload['error'] !== UPLOAD_ERR_OK ) {
if ( $upload['error'] === UPLOAD_ERR_INI_SIZE ) {
$this->_error = "File exceeds maximum file upload size";
}
else {
$this->_error = "There was an error uploading the file (".$upload['error'].")";
}
return false;
}
// Validation - acceptable file extensions
if ( is_array( $this->_extns ) ) {
$extn = pathinfo($upload['name'], PATHINFO_EXTENSION);
if ( in_array( strtolower($extn), array_map( 'strtolower', $this->_extns ) ) === false ) {
$this->_error = $this->_extnError;
return false;
}
}
// Validation - custom callback
for ( $i=0, $ien=count($this->_validators) ; $i<$ien ; $i++ ) {
$res = $this->_validators[$i]( $upload );
if ( is_string( $res ) ) {
$this->_error = $res;
return false;
}
}
// Database
if ( $this->_dbTable ) {
foreach ( $this->_dbFields as $column => $prop ) {
// We can't know what the path is, if it has moved into place
// by an external function - throw an error if this does happen
if ( ! is_string( $this->_action ) &&
($prop === self::DB_SYSTEM_PATH || $prop === self::DB_WEB_PATH )
) {
$this->_error = "Cannot set path information in database ".
"if a custom method is used to save the file.";
return false;
}
}
// Commit to the database
$id = $this->_dbExec( $upload, $editor->db() );
}
// Perform file system actions
return $this->_actionExec( $upload, $id );
}
/**
* Get the primary key column for the table
*
* @return string Primary key column name
* @internal
*/
public function pkey ()
{
return $this->_dbPKey;
}
/**
* Get the db table name
*
* @return string DB table name
* @internal
*/
public function table ()
{
return $this->_dbTable;
}
/* * * * * * * * * * * * * * * * * * * * * * * * *
* Private methods
*/
/**
* Execute the configured action for the upload
*
* @param array $upload $_FILES['upload']
* @param int $id Primary key value
* @return int File identifier - typically the primary key
*/
private function _actionExec ( $upload, $id )
{
if ( ! is_string( $this->_action ) ) {
// Custom function
$action = $this->_action;
return $action( $upload, $id );
}
// Default action - move the file to the location specified by the
// action string
$to = $this->_path( $upload['name'], $id );
$res = rename( $upload['tmp_name'], $to );
if ( $res === false ) {
$this->_error = "An error occurred while moving the uploaded file.";
return false;
}
if ($this->_mode) {
chmod($to, $this->_mode);
}
return $id !== null ?
$id :
$to;
}
/**
* Perform the database clean by first getting the information about the
* orphaned rows and then calling the callback function. The callback can
* then instruct the rows to be removed through the return value.
*
* @param \DataTables\Database $db Database instance
* @param string $editorTable Editor Editor instance table name
* @param string $fieldName Host field's name
*/
private function _dbClean ( $db, $editorTable, $fieldName )
{
$callback = $this->_dbCleanCallback;
if ( ! $this->_dbTable || ! $callback ) {
return;
}
// If there is a table / field that we should use to check if the value
// is in use, then use that. Otherwise we'll try to use the information
// from the Editor / Field instance.
if ( $this->_dbCleanTableField ) {
$fieldName = $this->_dbCleanTableField;
}
$a = explode('.', $fieldName);
if ( count($a) === 1 ) {
$table = $editorTable;
$field = $a[0];
}
else if ( count($a) === 2 ) {
$table = $a[0];
$field = $a[1];
}
else {
$table = $a[1];
$field = $a[2];
}
// Select the details requested, for the columns requested
$q = $db
->query( 'select' )
->table( $this->_dbTable )
->get( $this->_dbPKey );
foreach ( $this->_dbFields as $column => $prop ) {
if ( $prop !== self::DB_CONTENT ) {
$q->get( $column );
}
}
$q->where( $this->_dbPKey, '(SELECT '.$field.' FROM '.$table.' WHERE '.$field.' IS NOT NULL)', 'NOT IN', false );
$data = $q->exec()->fetchAll();
if ( count( $data ) === 0 ) {
return;
}
$result = $callback( $data );
// Delete the selected rows, iff the developer says to do so with the
// returned value (i.e. acknowledge that the files have be removed from
// the file system)
if ( $result === true ) {
$qDelete = $db
->query( 'delete' )
->table( $this->_dbTable );
for ( $i=0, $ien=count( $data ) ; $i<$ien ; $i++ ) {
$qDelete->or_where( $this->_dbPKey, $data[$i][ $this->_dbPKey ] );
}
$qDelete->exec();
}
}
/**
* Add a record to the database for a newly uploaded file
*
* @param array $upload $_FILES['upload']
* @param \DataTables\Database $db Database instance
* @return int Primary key value for the newly uploaded file
*/
private function _dbExec ( $upload, $db )
{
$pathFields = array();
$insertedId = null;
// Insert the details requested, for the columns requested
$q = $db
->query( 'insert' )
->table( $this->_dbTable )
->pkey( $this->_dbPKey );
foreach ( $this->_dbFields as $column => $prop ) {
switch ( $prop ) {
case self::DB_READ_ONLY:
break;
case self::DB_CONTENT:
$q->set( $column, file_get_contents($upload['tmp_name']) );
break;
case self::DB_CONTENT_TYPE:
case self::DB_MIME_TYPE:
$finfo = finfo_open(FILEINFO_MIME);
$mime = finfo_file($finfo, $upload['tmp_name']);
finfo_close($finfo);
$q->set( $column, $mime );
break;
case self::DB_EXTN:
$extn = pathinfo($upload['name'], PATHINFO_EXTENSION);
$q->set( $column, $extn );
break;
case self::DB_FILE_NAME:
$q->set( $column, $upload['name'] );
break;
case self::DB_FILE_SIZE:
$q->set( $column, $upload['size'] );
break;
case self::DB_SYSTEM_PATH:
$pathFields[ $column ] = self::DB_SYSTEM_PATH;
$q->set( $column, '-' ); // Use a temporary value to avoid cases
break; // where the db will reject empty values
case self::DB_WEB_PATH:
$pathFields[ $column ] = self::DB_WEB_PATH;
$q->set( $column, '-' ); // Use a temporary value (as above)
break;
default:
$val = $prop;
// Callable function - execute to get the value
if ( is_callable($prop) && is_object($prop) ) {
$val = $prop( $db, $upload );
}
// If the primary key value was set - use that
if ( $column === $this->_dbPKey ) {
$insertedId = $val;
}
if (is_string($val) && ! empty($val)) {
// Allow for replacement of __ID__, etc when the value is a string
$pathFields[ $column ] = $val;
$q->set( $column, '-' ); // Use a temporary value (as above)
}
else {
$q->set( $column, $val );
}
break;
}
}
$res = $q->exec();
$id = $insertedId !== null
? $insertedId
: $res->insertId();
// Update the newly inserted row with the path information. We have to
// use a second statement here as we don't know in advance what the
// database schema is and don't want to prescribe that certain triggers
// etc be created. It makes it a bit less efficient but much more
// compatible
if ( count( $pathFields ) ) {
// For this to operate the action must be a string, which is
// validated in the `exec` method
$path = $this->_path( $upload['name'], $id );
$webPath = str_replace($_SERVER['DOCUMENT_ROOT'], '', $path);
$q = $db
->query( 'update' )
->table( $this->_dbTable )
->where( $this->_dbPKey, $id );
foreach ( $pathFields as $column => $type ) {
$q->set( $column, $type === self::DB_WEB_PATH ? $webPath : $path );
}
$q->exec();
}
return $id;
}
/**
* Apply macros to a user specified path
*
* @param string $name File path
* @param int $id Primary key value for the file
* @return string Resolved path
*/
private function _path ( $name, $id )
{
$extn = pathinfo( $name, PATHINFO_EXTENSION );
$to = $this->_action;
$to = str_replace( "__NAME__", $name, $to );
$to = str_replace( "__ID__", $id, $to );
$to = str_replace( "__EXTN__", $extn, $to );
return $to;
}
}