Documentation

FileUploadController extends Controller
in package

Application

Handles file uploads in chunks using the JS File API and XMLHttpRequest

Constants

ALLOW_PRODUCTION : mixed = TRUE
MAX_CHUNK_COUNT : mixed = 512: Maximum number of chunks that can be uploaded per field-session

Properties

$action_log : mixed: Should this controller log add/edit/delete actions?

Methods

__call() : void: Handles methods that do not exist.
__construct() : void
_run() : mixed: The router/kohana will invoke this method to invoke an action.
chunkSizeCheck() : void: Perform a size check on a set of uploaded chunks.
clearSession() : mixed
extraChunkCheck() : void: Perform additional checks (beyond the checks already in {@see FileUploadController::uploadChunk}) on an uploaded chunk.
fileExtCheck() : mixed: Perform a file extension check.
fileSizeCheck() : mixed: Perform a size check on a completed upload (after chunks have been stitched).
getAbsModulePath() : string: Get the absolute path of the current module for this controller.
getCssClassName() : string: Return the class name for this controller, expressed in CSS style, i.e. with dashes
getModule() : ModuleInterface|null: Get the module that this controller belongs to.
getModulePath() : string: Get the a prefix suitable for finding views for this controller.
session() : array<string|int, mixed>: Gets the session data associated with a file upload
uploadBegin() : mixed: Signals that the user would like to upload a file Perform basic sanity checks and establish (or reset) their session state
uploadCancel() : void: Cancel an upload - delete temporary files.
uploadChunk() : void: Save a single chunk of a multi-part file upload
uploadDone() : void: Stitch together uploaded chunks into an actual file
uploadForm() : void: Returns the form for updating a file which has been uploaded
autoSetEmptyParam() : void: Auto-set the "empty" param for fields with foreign keys to be NULL
cleanupChunks() : void
deleteRecord() : int: Deletes a record, and logs the deletion This should be used by all _deleteSave methods Starts a transaction and commits it if not already in a transaction when called
generateFormView() : PhpView: Generates a form view from a JSON config file
jsonExtraValidate() : void: Do any additional validation prior to saving the record
loadEditJson() : array<string, array<string|int, array<string, mixed>>>: Loads a JSON config file for an automated edit-type form for this controller
loadFormJson() : array<string|int, mixed>: Loads a config file for a JsonForm associated with this controller
loadRecord() : array<string|int, mixed>|bool: Fetches the pre-update record from the database.
logAction() : int: Stores a history item in the database, recording an add (i.e. insert), edit, or delete.
logAdd() : int: Logs an add action. This is a wrapper for {@see Controller::logAction}
logAddCategory() : int: Logs the adding of a record to a category. This is a wrapper for {@see Controller::logAction}
logDelete() : int: Logs a delete action. This is a wrapper for {@see Controller::logAction}
logDeleteCategory() : int: Logs the removal of a record from a category. This is a wrapper for {@see Controller::logAction}
logEdit() : int: Logs an edit action. This is a wrapper for {@see Controller::logAction}
replaceSet() : void: Inserts records which are in $new_records, but are not in the specified table Deletes records which are in the specified table, but not in $new_records Updates records which are in both
saveJsonData() : bool: Automatically saves the data associated with a submission on a JSON-generated form
startSession() : array<string|int, mixed>: Creates a session record for a new file upload, and configures its initial state
validateCode() : string: Checks POSTed code matched the expected format
stitchChunks() : int

ALLOW_PRODUCTION


    public
        mixed
    ALLOW_PRODUCTION
    = TRUE

MAX_CHUNK_COUNT

Maximum number of chunks that can be uploaded per field-session


    public
        mixed
    MAX_CHUNK_COUNT
    = 512

$action_log

Should this controller log add/edit/delete actions?


        protected
            mixed
    $action_log
     = false

__call()

Handles methods that do not exist.


    public
                    __call(string $method, array<string|int, mixed> $args) : void

Parameters

$method : string: Method name
$args : array<string|int, mixed>: Arguments

__construct()


    public
                    __construct() : void

_run()

The router/kohana will invoke this method to invoke an action.


    public
                    _run(mixed $method, mixed $args) : mixed

Parameters

$method : mixed
$args : mixed

chunkSizeCheck()

Perform a size check on a set of uploaded chunks.


    public
                    chunkSizeCheck() : void

To be implemented by subclasses

clearSession()


    public
                    clearSession() : mixed

extraChunkCheck()

Perform additional checks (beyond the checks already in {@see FileUploadController::uploadChunk}) on an uploaded chunk.


    public
                    extraChunkCheck() : void

To be implemented by subclasses

fileExtCheck()

Perform a file extension check.


    public
                    fileExtCheck(mixed $temp_path) : mixed

To be implemented by subclasses

Parameters

$temp_path : mixed

fileSizeCheck()

Perform a size check on a completed upload (after chunks have been stitched).


    public
                    fileSizeCheck(string $temp_path) : mixed

To be implemented by subclasses

Parameters

$temp_path : string: Path to the temporary uploaded file

getAbsModulePath()

Get the absolute path of the current module for this controller.


    public
                    getAbsModulePath() : string

TODO this might be too broad. It's only used for loading JSON forms and perhaps encourages bad behaviour. Such as assuming common path structures for all modules, where instead this should be written into the module class.

Return values

string

getCssClassName()

Return the class name for this controller, expressed in CSS style, i.e. with dashes


    public
                    getCssClassName() : string

Example: When called from BlogPostController --> 'blog-post-controller'

Return values

string —

Name of this PHP class, in a format suitable for use in CSS

getModule()

Get the module that this controller belongs to.


    public
                    getModule() : ModuleInterface|null

If the controllers belongs to Sprout itself, this returns null.

Return values

ModuleInterface|null

getModulePath()

Get the a prefix suitable for finding views for this controller.


    public
                    getModulePath() : string

Do not assume that all modules, or even core sprout live relative to each other or the DOCROOT (as they previously did).

TODO rename this - like getViewPrefix()

Return values

string —

'sprout' or 'modules/AwesomeModule'

session()

Gets the session data associated with a file upload


    public
                &    session() : array<string|int, mixed>

Return values

array<string|int, mixed>

uploadBegin()

Signals that the user would like to upload a file Perform basic sanity checks and establish (or reset) their session state


    public
                    uploadBegin() : mixed

uploadCancel()

Cancel an upload - delete temporary files.


    public
                    uploadCancel() : void

May receive two different variations on the provided POST data: [result][tmp_file] Whole file was uploaded [partial_upload][code] Only some chunks of the file have been uploaded

uploadChunk()

Save a single chunk of a multi-part file upload


    public
                    uploadChunk() : void

Return values

void —

Outputs JSON

uploadDone()

Stitch together uploaded chunks into an actual file


    public
                    uploadDone() : void

Outputs a JSON response. The field "success" will be checked (= 1) to determine success. On error, the field "message" will be used as an error message. Other keys provided are passed to the ajaxDragdropForm method.

Return values

void —

Outputs JSON

uploadForm()

Returns the form for updating a file which has been uploaded


    public
                    uploadForm() : void

Return values

void —

Outputs HTML

autoSetEmptyParam()

Auto-set the "empty" param for fields with foreign keys to be NULL


    protected
                    autoSetEmptyParam(array<string, array<string|int, array<string, mixed>>> &$conf) : void

This greatly reduces the number of foreign-key constraints hit in day-to-day use, especially with file fields.

Parameters

$conf : array<string, array<string|int, array<string, mixed>>>: Json form configuration

Return values

void —

Array $conf is altered in-place

cleanupChunks()


    protected
                    cleanupChunks(string $code, int|string $num_chunks) : void

Parameters

$code : string
$num_chunks : int|string

deleteRecord()

Deletes a record, and logs the deletion This should be used by all _deleteSave methods Starts a transaction and commits it if not already in a transaction when called


    protected
                    deleteRecord(string $table, int $record_id[, int $parent_log_id = 0 ]) : int

Parameters

$table : string: Table name
$record_id : int
$parent_log_id : int = 0: ID of a parent entry in the history_items table. This is used when multiple records are deleted by a single action. Undoing that action can then restore all of the deleted data.

Return values

int —

ID of the record inserted into the history_items table (0 if no logging)

generateFormView()

Generates a form view from a JSON config file


    protected
                    generateFormView(mixed $file_name) : PhpView

Parameters

$file_name : mixed

Return values

PhpView

jsonExtraValidate()

Do any additional validation prior to saving the record


    protected
                    jsonExtraValidate(int $id, Validator $validator) : void

Parameters

$id : int: Record ID or 0 for adds
$validator : Validator: Validator instance to attach your errors to

loadEditJson()

Loads a JSON config file for an automated edit-type form for this controller


    protected
                    loadEditJson() : array<string, array<string|int, array<string, mixed>>>

Return values

array<string, array<string|int, array<string, mixed>>>

loadFormJson()

Loads a config file for a JsonForm associated with this controller


    protected
                    loadFormJson(string $file_name) : array<string|int, mixed>

Parameters

$file_name : string: The config file name, e.g. 'register.json'

Return values

array<string|int, mixed>

loadRecord()

Fetches the pre-update record from the database.


    protected
                    loadRecord(string $table, int $record_id) : array<string|int, mixed>|bool

Used by the action log system, and disabled if the action log system has been turned off

Parameters

$table : string: Name of table to load record from
$record_id : int: ID of record to load

Return values

array<string|int, mixed>|bool —

False if not using logging for this controller, else the record row

logAction()

Stores a history item in the database, recording an add (i.e. insert), edit, or delete.


    protected
                    logAction(string $table, int $record_id, string $type[, array<string|int, mixed> $data = [] ][, int $parent_log_id = 0 ]) : int

Should be called AFTER the action has been made. N.B. This is a low-level method; the friendlier wrapper methods are preferred; e.g. Controller::logAdd, Controller::logEdit

Parameters

$table : string: The table which had data modified by the query
$record_id : int: The id of the added/edited/deleted record
$type : string: ENUM value from history_items.type
$data : array<string|int, mixed> = []: Data associated with an add/edit. The handling differs based on the $type parameter: 'Add' ignored 'Edit' should be an array of the pre-update data, used to build a diff 'Delete' should contain the complete data of the deleted record 'Add category' should contain ['cat_id' => value] 'Delete category' should contain ['cat_id' => value] 'Change password' should be an empty array
$parent_log_id : int = 0: ID of a parent log entry in the history_items table. This is used when multiple records are deleted by a single action. Undoing that action can then restore all of the deleted data. N.B. This is only relevant for deletes

Return values

int —

ID of the record inserted into the history_items table; 0 if no insert was done; -1 if it failed

logAdd()

Logs an add action. This is a wrapper for {@see Controller::logAction}


    protected
                    logAdd(string $table, int $record_id) : int

Parameters

$table : string: The table which had data modified by the query
$record_id : int: The id of the added record

Return values

int —

ID of the record inserted into the history_items table

logAddCategory()

Logs the adding of a record to a category. This is a wrapper for {@see Controller::logAction}


    protected
                    logAddCategory(string $table, int $record_id, int $cat_id) : int

Parameters

$table : string: The table which had data modified by the query
$record_id : int: The ID of the record which was added to the category
$cat_id : int: The ID of the category which the record was added to

Return values

int —

ID of the record inserted into the history_items table

logDelete()

Logs a delete action. This is a wrapper for {@see Controller::logAction}


    protected
                    logDelete(string $table, int $record_id, array<string|int, mixed> $data[, int $parent_log_id = 0 ]) : int

Parameters

$table : string: The table which contained the deleted record
$record_id : int: The id of the deleted record
$data : array<string|int, mixed>: The complete contents of the record which was deleted, i.e. [field => value], so it can be restored if necessary
$parent_log_id : int = 0: ID of a parent log entry in the history_items table. This is used when multiple records are deleted by a single action. Undoing that action can then restore all of the deleted data.

Return values

int —

ID of the record inserted into the history_items table

logDeleteCategory()

Logs the removal of a record from a category. This is a wrapper for {@see Controller::logAction}


    protected
                    logDeleteCategory(string $table, int $record_id, int $cat_id) : int

Parameters

$table : string: The table which contains the record which was removed from the category
$record_id : int: The ID of the record which was removed from the category
$cat_id : int: The ID of the category which the record was removed from

Return values

int —

ID of the record inserted into the history_items table

logEdit()

Logs an edit action. This is a wrapper for {@see Controller::logAction}


    protected
                    logEdit(string $table, int $record_id, array<string|int, mixed> $data) : int

Parameters

$table : string: The table which had data modified by the query
$record_id : int: The id of the edited record
$data : array<string|int, mixed>: Pre-update data, used to build a diff

Return values

int —

ID of the record inserted into the history_items table

replaceSet()

Inserts records which are in $new_records, but are not in the specified table Deletes records which are in the specified table, but not in $new_records Updates records which are in both


    protected
                    replaceSet(string $table, array<string|int, mixed> $new_records, array<string|int, mixed> $conditions) : void

Matching is done on the 'id' field, as a result the $new_records arrays MUST contain an id field.

Parameters

$table : string: The table name. Do not include prefix.
$new_records : array<string|int, mixed>: The new records for the table. Should be an array of arrays, With each sub-array being the arguments which would normally be passed to Pdb::insert or Pdb::update
$conditions : array<string|int, mixed>: A where clause to use when looking to see what records already exist. Pdb::buildClause

saveJsonData()

Automatically saves the data associated with a submission on a JSON-generated form


    protected
                    saveJsonData(array<string, array<string|int, array<string, mixed>>> $conf, int &$item_id[, string $mode = '' ]) : bool

Parameters

$conf : array<string, array<string|int, array<string, mixed>>>: Config loaded from a JSON file
$item_id : int: Database ID of record to store data in. If zero, a new record will be inserted, and as this argument is a reference, it will be updated with the auto-increment ID generated by the insert.
$mode : string = '': Mode: 'add', 'edit', or something custom (e.g. 'duplicate', 'verify'). If blank, 'add' or 'edit' will be automatically determined, based on $item_id

Return values

bool —

True if the save succeeded. If false is returned, errors will be saved in $_SESSION

startSession()

Creates a session record for a new file upload, and configures its initial state


    protected
                &    startSession() : array<string|int, mixed>

Return values

array<string|int, mixed>

validateCode()

Checks POSTed code matched the expected format


    protected
                    validateCode() : string

Return values

string —

The code itself, if it's valid

stitchChunks()


    private
                    stitchChunks(string $dest_filename, string $code, int|string $num_chunks) : int

Parameters

$dest_filename : string
$code : string
$num_chunks : int|string

Return values

int

FileUploadController extends Controller in package Application

Table of Contents

Constants

Properties

Methods

Constants

ALLOW_PRODUCTION

MAX_CHUNK_COUNT

Properties

$action_log

Methods

__call()

Parameters

Tags

__construct()

_run()

Parameters

Tags

chunkSizeCheck()

clearSession()

extraChunkCheck()

fileExtCheck()

Parameters

Tags

fileSizeCheck()

Parameters

Tags

getAbsModulePath()

Return values

getCssClassName()

Return values

getModule()

Return values

getModulePath()

Return values

session()

Return values

uploadBegin()

Tags

uploadCancel()

uploadChunk()

Tags

Return values

uploadDone()

Tags

Return values

uploadForm()

Tags

Return values

autoSetEmptyParam()

Parameters

Return values

cleanupChunks()

Parameters

deleteRecord()

Parameters

Tags

Return values

generateFormView()

Parameters

Tags

Return values

jsonExtraValidate()

Parameters

loadEditJson()

Tags

Return values

loadFormJson()

Parameters

Tags

Return values

loadRecord()

Parameters

Tags

Return values

logAction()

Parameters

Tags

Return values

logAdd()

FileUploadController extends Controller
in package

Application