Class Db_File

Db_File class

Defined in	/phproad/modules/db/models/db_file.php, lines 48-499
Inheritance	Phpr_Extension » Phpr_Extensible » Phpr_Validatable » Db_Base » Db_WhereBase » Db_SqlBase » Db_ActiveRecord » Db_File
Subclasses	Shop_ProductFile
Author	LemonStand eCommerce Inc.

Represents a file or image attached to a model. This class used for creating model relations which contain model attachments. Please note that downloadable product files are presented with another class - Shop_ProductFile. The example below demonstrates a typical relation which can be presented as a single file, single image, multiple file or multiple image widget on the form, depending in the value passed to the field's Db_FormFieldDefinition::renderFilesAs() method:

public $has_many = array(
 'images'=>array('class_name'=>'Db_File', 'foreign_key'=>'master_object_id', 
   'conditions'=>"master_object_class='Shop_Product' and field='images'", 
   'order'=>'sort_order, id', 'delete'=>true)
);

Note that the conditions parameter should define a SQL filter which refers to the model class name (Shop_Product in the example) and the relation name (image in the example). File relations should always be defined as has_many. Defining the relation is enough if you are not going to display files in the model form. If administrators should be able to upload files, you should define the model column and form field as described below.

After adding the relations a corresponding column should be created with Db_ActiveRecord::define_multi_relation_column() method:

public function define_columns($context = null)
{
  $this->define_multi_relation_column('images', 'images', 'Images', '@name')->invisible();
}

And finally, the field should be added to the form with Db_ActiveRecord::define_form_fields() method. The type of the form widget is defined with Db_FormFieldDefinition::renderFilesAs() method.

public function define_form_fields($context = null)
{
  $this->add_form_field('images')->renderAs(frm_file_attachments)->renderFilesAs('image_list')
    ->addDocumentLabel('Add image(s)')->tab('Images')->noAttachmentsLabel('There are no images uploaded')
    ->fileDownloadBaseUrl(url('ls_backend/files/get/'));
}

Public properties

Show inherited properties.

Property	Type	Description	Defined By
auto_create_timestamps	array	a list of create timestamp columns.	Db_ActiveRecord
auto_timestamps	boolean	determines whether create and update timestamp field should be set automatically.	Db_ActiveRecord
auto_update_timestamps	array	a list of update timestamp columns.	Db_ActiveRecord
belongs_to	array	contains a list of Belongs To Many relations.	Db_ActiveRecord
custom_columns	array	contains a list of custom fields definition.	Db_ActiveRecord
description	string	specifies the file description.	Db_File
fetched	array	contains an associative array of table column values fetched from the database.	Db_ActiveRecord
has_and_belongs_to_many	array	contains a list of Has and Belongs To Many relations.	Db_ActiveRecord
has_many	array	contains a list of Has Many relations.	Db_ActiveRecord
has_one	array	contains a list of Has One relations.	Db_ActiveRecord
id	integer	specifies the file record identifier.	Db_File
is_public	boolean	determines whether the file on the server can be accessed from the Web.	Db_File
name	string	specifies the file name.	Db_File
primary_key	string	specifies a name of the table primary key.	Db_ActiveRecord
size	integer	specifies the file size, in bytes.	Db_File
title	string	specifies the file tittle.	Db_File
validation	Phpr_Validation	contains the model's validation object.	Db_ActiveRecord

Public methods

Show inherited methods.

Method	Description	Defined By
add_form_custom_area()	adds a form custom area.	Db_ActiveRecord
add_form_field()	makes a column visible in forms.	Db_ActiveRecord
add_form_partial()	adds a custom form partial.	Db_ActiveRecord
add_form_section()	adds a form section.	Db_ActiveRecord
after_create_saved()	called after a new object is saved to the database.	Db_ActiveRecord
after_modify()	called after an existing or new record was modified.	Db_ActiveRecord
after_save()	called after an existing or new record is created or updated in the database.	Db_ActiveRecord
after_update()	called after an existing record is updated in the database.	Db_ActiveRecord
after_validation()	triggered after the model column values are validated.	Db_ActiveRecord
after_validation_on_create()	triggered after a new model column values are validated.	Db_ActiveRecord
after_validation_on_update()	triggered after an existing model column values are validated.	Db_ActiveRecord
before_delete()	called before a record is deleted from the database.	Db_ActiveRecord
before_save()	called before an existing or new record is created or updated in the database.	Db_ActiveRecord
before_update()	called before an existing record is updated in the database.	Db_ActiveRecord
before_validation()	triggered before the model column values are validated.	Db_ActiveRecord
before_validation_on_create()	triggered before a new model column values are validated.	Db_ActiveRecord
before_validation_on_update()	triggered before an existing model column values are validated.	Db_ActiveRecord
collection()	executes the find_all() method and returns a collection.	Db_ActiveRecord
columnValue()	alias for the displayField() method.	Db_ActiveRecord
copy()	copies the file and returns the new file object.	Db_File
create()	creates a new class instance.	Db_File
define_column()	adds a column definition to the model.	Db_ActiveRecord
define_form_fields()	defines form fields.	Db_ActiveRecord
define_multi_relation_column()	adds column definition for has_and_belongs_to_many or has_many relation field.	Db_ActiveRecord
define_relation_column()	adds column definition for has_on or belongs_to relation field.	Db_ActiveRecord
delete()	deletes the record from the database.	Db_ActiveRecord
delete_form_field()	deletes a form field by its corresponding column name.	Db_ActiveRecord
displayField()	returns a formatted column value. The field should be defined with define_column(),	Db_ActiveRecord
find()	finds a record by its primary key value.	Db_ActiveRecord
find_all()	finds all records and returns the Db_DataCollection object, containing a list of models.	Db_ActiveRecord
find_by()	finds a record by a field value.	Db_ActiveRecord
find_column_definition()	finds a column definition by the column name.	Db_ActiveRecord
find_form_field()	finds a form field definition by its corresponding column name.	Db_ActiveRecord
fromFile()	creates a file object from a disk file.	Db_File
getPath()	returns the file path relative to LemonStand root directory.	Db_File
getThumbnailPath()	creates an image thumbnail.	Db_File
is_image()	returns TRUE if the file is an image.	Db_File
join()	adds a table to the query with JOIN statement.	Db_SqlBase
limit()	allows to limit the result of the find_all() method with the specified number of records.	Db_ActiveRecord
list_related_records_deferred()	returns a list of relation objects, taking into account deferred relations.	Db_ActiveRecord
order()	allows to order the result of the find_all() method by a specific table column.	Db_SqlBase
orWhere()	adds OR statement to the where clause, allowing to to limit the result of the find() and find_all() methods with SQL filter.	Db_WhereBase
output()	outputs the file to the browser.	Db_File
paginate()	allows to limit the result of the find_all() method with a single page of records.	Db_ActiveRecord
requestRowCount()	returns a number of rows which would be returned with find_all() method.	Db_ActiveRecord
save()	saves record to the database.	Db_ActiveRecord
thumb()	this method is an alias for the getThumbnailPath() method.	Db_File
where()	allows to limit the result of the find() and find_all() methods with SQL filter.	Db_WhereBase

Protected methods

Show inherited methods.

Method	Description	Defined By
define_columns()	defines model columns.	Db_ActiveRecord

Events

Event	Description
core:onFileBeforeCreate	Triggered before a new file record saved to the database.
core:onProcessImage	Allows to process product and other images with third-party image manipulation tools.

Property details

¶ description property

public string $description;

Specifies the file description.

¶ id property

public integer $id;

Specifies the file record identifier.

¶ is_public property

public boolean $is_public;

Determines whether the file on the server can be accessed from the Web. Public files are stored to uploaded/public directory, which is open for the external access. The form behavior considers image files (rendered as single image or image lists) as public, and all other files as non public.

¶ name property

public string $name;

Specifies the file name.

¶ size property

public integer $size;

Specifies the file size, in bytes.

¶ title property

public string $title;

Specifies the file tittle.

Method details

¶ copy() method

public Db_File copy()

{return}	Db_File	returns the new file object.

Copies the file and returns the new file object. The returned object is not saved to the database, so its properties can be updated before it is saved.

¶ create() method

public static Db_File create(array $values=NULL)

$values	array	optional list of column values.
{return}	Db_File	returns the file object.

Creates a new class instance.

¶ fromFile() method

public Db_File fromFile(string $file_path)

$file_path	string	specifies a path to the file.
{return}	Db_File	returns the initialized file.

Creates a file object from a disk file. Use this method for adding files from disk to a list of model's files.

$file = Db_File::create()->fromFile(PATH_APP.'/temp/picture.png');
$file->is_public = true;
$file->master_object_class = 'Shop_Product';
$file->field = 'images';
$file->save();

$product->images->add($file);
$product->save();

¶ getPath() method

public string getPath()

{return}	string	returns the file path.

Returns the file path relative to LemonStand root directory. Use PATH_APP constant to obtain the absolute path:

$absolute_path = PATH_APP.$file->getPath();

¶ getThumbnailPath() method

public string getThumbnailPath(mixed $width, mixed $height, boolean $as_jpeg=true, array $params=array( 'mode'=>'keep_ratio'))

$width	mixed	specifies the thumbnail width. Use the 'auto' word to scale image width proportionally.
$height	mixed	specifies the thumbnail height. Use the 'auto' word to scale height width proportionally.
$as_jpeg	boolean	determines whether JPEG or PNG image will be created.
$params	array	a list of parameters.
{return}	string	returns the image URL relative to the website root.

Creates an image thumbnail. This method is applicable only for image files. The $width and $height parameters could be either integer numbers or the 'auto' word. If you specify an integer number for the width or height, the thumbnail will have the exact width or height value, in pixels. Use the 'auto' word to scale an image dimension proportionally. For example, to generate a thumbnail with fixed width of 100 pixels and proportional height, use the following code:

$url = $file->getThumbnailPath(100, 'auto');

The $as_jpeg parameter allows you to generate PNG images with transparency support. By default the parameter value is TRUE and the method generates a JPEG image. The $params array allows to pass parameters to image processing modules (which handle the core:onProcessImage event).

Behavior of this method can be altered by core:onProcessImage event handlers.

¶ is_image() method

public boolean is_image()

{return}	boolean	returns TRUE if the file is an image.

Returns TRUE if the file is an image. The method detect images basing on the file extension. The following extensions are considered as images: jpeg, jpg, gif, png.

¶ output() method

public void output(string $disposition='inline')

$disposition	string	specifies the content disposition HTTP header value: inline or attachment.

Outputs the file to the browser. Depending on the file type and $disposition parameter value a browser either displays the file contents or offers to save it to the disk.

¶ thumb() method

public string thumb(mixed $width, mixed $height, boolean $as_jpeg=true, array $params=array( 'mode'=>'keep_ratio'))

$width	mixed	specifies the thumbnail width. Use the 'auto' word to scale image width proportionally.
$height	mixed	specifies the thumbnail height. Use the 'auto' word to scale height width proportionally.
$as_jpeg	boolean	determines whether JPEG or PNG image will be created.
$params	array	a list of parameters.
{return}	string	returns the image URL relative to the website root.

This method is an alias for the getThumbnailPath() method. Creates an image thumbnail.

LemonStand API