File

Description

The File model is typically connected to your own models via the file or files field.

It represents a single file in the database. Each file will have a physical file associated with it the /data/ folder but most often you will never directly access this file and instead use helper functions like download().

Properties

• name – a name, usually the original file name of the file
• status – will be ‘new’, ‘uploaded’, ‘saved’, or ‘deleted’ depending on its current status. ‘uploaded’ means it exists and has been created but is not yet associated with an object. ‘saved’ means it is.
• class – the class of the model it is associated with
• parent – the id of the model it is associated with
• field – the field in the model it is associated with
• extension – will be the end of the file, ‘pdf’, ‘zip’, etc
• mime – the mime type of the file
• relative – the path, relative to basepath
• path – alias of relative
• temporary – if set to true, the file is not yet saved to the database. usually you do not need to use this unless you are developing internals. read-only value from outside the object.
• id – the object id

Model data

You can access the following model data fields via the data property (example {{file.data.name}}):

• class – string – the class of the model it is associated with
• parent – string – the id of the model it is associated with
• field – string – the field in the model it is associated with
• name – string – a name, usually the original file name of the file
• description – string – a longer text about this file
• status – will be ‘new’, ‘uploaded’, ‘saved’, or ‘deleted’ depending on its current status. ‘uploaded’ means it exists and has been created but is not yet associated with an object. ‘saved’ means it is.
• mime – string – the mime type of the file
• size – integer – the size of the file in bytes
• time_create – integer – unix timestamp of when object was created
• time_edit – integer – unix timestamp of when object was last modified
• ordernum – integer – the default sorting number (autoincremented)
• id – string – the unique id

get_file_path()

Helper function which returns the final path based on the current settings.

$file-> get_file_path();

@param string|boolean $filename Defaults to the standard file name.
@param boolean $create_folders Create the subfolders if needed.
@return string Returns the file path, relative to basepath.

get_temporary_path()

Helper function which returns the temporary path where the file is stored after upload but before save.

$file->get_temporary_path();

@param boolean $create_folders Create the subfolders if needed.
@return string Returns the file path, relative to basepath.

download()

Forces a download dialog for the browser.

@param boolean $force_download If set to true (default), this will force a download for the user.
@param string|boolean $download_as The file name to download as. Defaults to the uploaded file name.
@return void|boolean This will force a download and exit. May return false if it fails.

show()

Shows the file in the browser inline (if available). This will work on certain files and configurations (PDF files in certain browsers) but is not reliable.

@param string|boolean $file_name The file name to download as if the file is downloaded instead of shown. Defaults to the uploaded file name.
@return void|boolean This will try to show the file inline and exit.

duplicate()

Overrides the global duplicate method and copies the physical file as well. Unlike the standard duplicate method, this actually saves the object.

@param string|boolean $id Use this to override random id generation.
@return File Returns a new file object with the physical file duplicated as well.

upload()

Method which saves file to its final location. Usually you don’t need to use this – calling save() on an object where there is a File reliationship will trigger this.

delete()

Overrides the global delete such that setting the parameter to true will delete all associated files as well.

$file->delete($complete = false)

@param bool $complete If set to true, the file will be deleted too and the full entry will be removed.
@return bool Returns true if successful.

create_with_parent()

Static method. Creates a file with a specific parent object and field.

File::create_with_parent($parent, $field)

@param zajModel|string $parent The parent object.
@param string $field The name of the field.
@return File |boolean Returns a new bare file object with the parent and field set.

create_from_file()

Static method. Creates and saves a file object from a file or url. Will return false if it is not an image or not found.

File::create_from_file($url_or_file_name, $parent = false, $field = null, $save_now_to_final_destination = true)

@param string $url_or_file_name The url or file name.
@param zajModel|bool $parent My parent object or id. If not specified, none will be set.
@param string|bool $field The field name of the parent. This is required if $parent is set.
@param boolean $save_now_to_final_destination If set to true (the default) it will be saved in the final folder immediately. Otherwise it will stay in the tmp folder.
@return File|boolean Returns the new file object or false if none created.

create_from_url()

Alias of create_from_file() but also validates the url.

create_from_stream()

Static method. Creates a file object from php://input stream.

File::create_from_stream($parent = false, $field = null, $save_now_to_final_destination = true)

@param zajModel|bool $parent My parent object.
@param string|bool $field The field name of the parent. This is required if $parent is set.
@param boolean $save_now_to_final_destination If set to true (the default) it will be saved in the final folder immediately. Otherwise it will stay in the tmp folder.
@return File |bool Returns the File object on success, false if not.

create_from_base64()

Static method. Creates a file object from base64 data.

File::create_from_base64($base64_data, $parent = false, $field = null, $save_now_to_final_destination = true)

@param string $base64_data This is the file data, base64-encoded.
@param zajModel|bool $parent My parent object.
@param string|bool $field The field name of the parent. This is required if $parent is set.
@param boolean $save_now_to_final_destination If set to true (the default) it will be saved in the final folder immediately. Otherwise it will stay in the tmp folder.
@return File|bool Returns the File object on success, false if not.

create_from_raw()

Static method. Create a file object from raw data.

File::create_from_raw($raw_data, $parent = false, $field = null, $save_now_to_final_destination = true)

@param string|boolean $raw_data If specified, this will be used instead of input stream data.
@param zajModel|bool $parent My parent object.
@param string|bool $field The field name of the parent. This is required if $parent is set.
@param boolean $save_now_to_final_destination If set to true (the default) it will be saved in the final folder immediately. Otherwise it will stay in the tmp folder.
@return File|bool Returns the File object on success, false if not.

create_from_upload()

Static method. Creates a file object from a standard upload HTML4.

File::create_from_upload($field_name, $parent = false, $field = null, $save_now_to_final_destination = true)

@param string $field_name The name of the file input field in HTML.
@param zajModel|bool $parent My parent object.
@param string|bool $field The field name of the parent. This is required if $parent is set.
@param boolean $save_now_to_final_destination If set to true (the default) it will be saved in the final folder immediately. Otherwise it will stay in the tmp folder.
@return File|bool Returns the File object on success, false if not.