Outlast

Photo

Description

The Photo model is typically connected to your own models via the photo or photos field.

It represents a single photo in the database. Each photo can have multiple sizes associated with it.

You can access the direct url of photos in the template system using the |photo filter or in PHP via the size properties.

Properties

name – a name, usually the original file name of the photo
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 – can be ‘png’, ‘gif’, or ‘jpg’
imagetype – its value is a PHP constant, IMAGETYPE_PNG, IMAGETYPE_GIF, or IMAGETYPE_JPEG
orientation – this value can be ‘portrait’ or ‘landscape’. 1:1 photos are also ‘landscape’, but they have their square param set to true
landscape – will be true if the photo is a landscape photo or if the sides are equal
portrait – will be true if the photo is a portrait photo
square – will be true if photo is 1:1
id – the object id

When a photo is uploaded, multiple sizes are generated so you can optimize layout. For each size name there are properties that contain the full or relative urls for each resized photo. Here are the defaults:

thumb – 50px wide picture, full url
rel_thumb – 50px wide picture, relative to baseurl or basepath
small – 300px wide picture, full url
rel_small – 300px wide picture, relative to baseurl or basepath
normal – 700px wide picture, full url
rel_normal – 700px wide picture, relative to baseurl or basepath
large – 2000px wide picture, full url
rel_large – 2000px wide picture, relative to baseurl or basepath
full – full, original width picture, full url
rel_full – full, original width picture, relative to baseurl or basepath

Please note, that these can be modified by changing the settings via $GLOBALS['photosizes'] array.

Smaller pictures are not resized to higher resolutions but you can still access their url via the above properties.

Model data

You can access the following model data fields via the data property (example {{photo.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 photo
description – string – a longer text about this photo
imagetype – integer – its value is a PHP constant, IMAGETYPE_PNG, IMAGETYPE_GIF, or IMAGETYPE_JPEG
cropdata – stdClass – Stores original photo data and associated cropping values as json data. Returned as a stdClass. Sample data: {“x”:0,”y”:0,”w”:540,”h”:525,”path”:’data/something/beforecrop.jpg’}. Path is empty if original not saved during crop.
filesizes – stdClass – Stores file sizes in bytes as json data. Sample data: {“thumb”:1757,”small”:16870,”normal”:42247,”large”:42247,”full”:42247}
dimensions – stdClass – Stores photo dimensions as json data. Sample data: {“thumb”:{“w”:50,”h”:63},”small”:{“w”:300,”h”:382},”normal”:{“w”:533,”h”:680},”large”:{“w”:533,”h”:680},”full”:{“w”:533,”h”:680}}
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.
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)

set_image()

Resizes and saves the image. The status is always changed to saved and this method automatically saves changes to the database. Only call this when you are absolutely ready to commit the photo for public use.

@param string $filename The name of the file within the cache upload folder.
@return bool|Photo Returns the Photo object, false if error.

get_image()

Returns an image url based on the requested size. Typically you should use the size properties instead.

$photo->get_image($size = 'normal');

@param string $size One of the standard photo sizes.
@return string Image url.

get_path()

Returns an image path based on the requested size. Typically you should use the relative size properties instead.

@param string $size One of the standard photo sizes.
@return string Image url.

show()

An alias of Photo->download($size, false), which will display the photo instead of forcing a download.

@param string $size One of the standard photo sizes.

download()

Forces a download dialog for the browser.

@param string $size One of the standard photo sizes.
@param boolean $force_download If set to true (default), this will force a download for the user.
@param string|boolean $file_name 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.

crop()

Creates new image files by cropping the current image.

@param integer $x Cropped image offset from left.
@param integer $y Cropped image offset from top.
@param integer $w Cropped image width.
@param integer $h Cropped image height.
@param integer $jpeg_quality A number value of the jpg quality to be used in conversion. Only matters for jpg output.
@param boolean $keep_a_copy_of_original If set to true (default), a copy of the original file will be kept.
@return boolean True if successful, false otherwise.

resize()

Create all of the defined size versions from the master file.

get_master_file_path()

Get the file path of the original image.

get_extension()

Get the file extension type.

get_extension($file_path = false)

@param string|boolean $file_path The path whoes extension we wish to check. Defaults to the master file path.
@return string Will return png, gif, or jpg.

delete()

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

$photo->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 photo with a specific parent object and field.

Photo::create_with_parent($parent, $field)

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

create_from_file()

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

Photo::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 Photo|boolean Returns the new photo object or false if none created.

create_from_stream()

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

Photo::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 Photo|bool Returns the Photo object on success, false if not.

create_from_base64()

Static method. Creates a photo object from base64 data.

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

@param string $base64_data This is the photo 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 Photo|bool Returns the Photo object on success, false if not.

create_from_raw()

Static method. Create a photo object from raw data.

Photo::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 Photo|bool Returns the Photo object on success, false if not.

create_from_upload()

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

Photo::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.
@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 Photo|bool Returns the Photo object on success, false if not.

API reference