|
Db_ActiveRecord class
Base class for LemonStand models.
Db_ActiveRecord class is a base class for many other LemonStand classes, including
Shop_Customer, Shop_Order, Cms_Page and others. The class has a number of
methods which enable you to find and update records in the database.
Properties of this class subclasses depend on the table fields they represent. If a table had name field, a corresponding model class would have public $name property. ActiveRecord uses the following constants for mapping data types:
$obj = new Shop_Customer();
$customer = $obj->where('first_name=?', 'John')->where('last_name=?', 'Doe')->find();
$customer->last_name = 'Smith';
$customer->save();
See AlsoPublic properties
Public methodsShow inherited methods.
Protected methods
Events
Property details¶ auto_create_timestamps propertypublic array $auto_create_timestamps;
A list of create timestamp columns.
Values of columns specified in this list are automatically
set when the new model object is saved to the database
By default created_at and created_on columns
are considered as create timestamp columns.
Setting the create timestamp column values takes place only if auto_timestamps property value is TRUE. ¶ auto_timestamps propertypublic boolean $auto_timestamps;
Determines whether create and update timestamp field should be set automatically.
By default columns specified in auto_create_timestamps and
auto_update_timestamps properties are set automatically when the model
is saved. Assign FALSE value to this property to cancel this behavior.
¶ auto_update_timestamps propertypublic array $auto_update_timestamps;
A list of update timestamp columns.
Values of columns specified in this list are automatically
set when an existing model object is saved to the database
By default updated_at and updated_on columns
are considered as update timestamp columns.
Setting the update timestamp column values takes place only if auto_timestamps property value is TRUE. ¶ belongs_to propertypublic array $belongs_to;
Contains a list of Belongs To Many relations.
Please read Creating data relations
article for details.
¶ calculated_columns propertypublic array $calculated_columns;
Contains a list of calculated columns.
Use this property to define calculated columns in your models. Calculated columns do not
exist in the data table. Instead they are calculated with SQL. Example:
public $calculated_columns = array(
'comment_num'=>'select count(*) from comments where post_id=post.id',
'disk_file_name'=>array('sql'=>'files.file_create_date', 'join'=>array('files'=>'files.post_id=post.id'), 'type'=>db_date)
);
$comment_num = $obj->comment_num; ¶ custom_columns propertypublic array $custom_columns;
Contains a list of custom fields definition.
Use this field to define custom columns in your models. Custom columns do not exist in the database
and their values a are evaluated with special model methods when the model is loaded from the database.
Each custom column should have a corresponding method in the model class.
Example:
public $custom_columns = array('record_status'=>db_number, 'record_css_class'=>db_text);
public function eval_record_status()
{
return 1;
}
public function eval_record_css_class()
{
return $this->deleted ? 'deleted' : 'normal';
}
$record_status = $obj->record_status; ¶ fetched propertypublic array $fetched;
Contains an associative array of table column values fetched from the database.
You can use this field to compare original values with new values before the model is saved
to the database.
¶ has_and_belongs_to_many propertypublic array $has_and_belongs_to_many;
Contains a list of Has and Belongs To Many relations.
Please read Creating data relations
article for details.
¶ has_many propertypublic array $has_many;
Contains a list of Has Many relations.
Please read Creating data relations
article for details.
¶ has_one propertypublic array $has_one;
Contains a list of Has One relations.
Please read Creating data relations
article for details.
¶ primary_key propertypublic string $primary_key;
Specifies a name of the table primary key.
Default primary key name is id. Override this
property in a model if its table has primary key with
another name.
¶ validation propertypublic Phpr_Validation $validation;
Contains the model's validation object.
This model uses this method during the validation process.
Method details¶ add_form_custom_area() methodpublic Db_FormCustomArea add_form_custom_area(string $id, string $location=NULL)
Adds a form custom area.
Form areas can contain arbitrary HTML markup. Form area contents should be defined in
a partial with name _form_area_name.htm in the controller's views directory,
where id is an area identifier specified in the method parameter. The optional
$location parameter allows to specify a path of a directory containing the partial.
¶ add_form_field() methodpublic Db_FormFieldDefinition add_form_field(string $dbName, $side $side='full')
Makes a column visible in forms.
The column should be defined with define_column(),
define_relation_column() or
define_multi_relation_column() method before this method is called.
The method returns the form field definition object which can be used for further configuration of the field. Example:
$this->add_form_field('author_name', 'left');¶ add_form_partial() methodpublic Db_FormPartial add_form_partial(string $path)
Adds a custom form partial.
Form partials can contain arbitrary HTML markup. Example:
$this->add_form_partial(PATH_APP.'/modules/mymodule/partials/_form_partial.htm'); ¶ add_form_section() methodpublic Db_FormSection add_form_section(string $description, string $title=NULL, string $html_id=NULL)
Adds a form section.
Form sections allow to separate form space with a title and description text.
¶ after_create() methodpublic void after_create()
Called after a new object is saved to the database.
Override this method in your model classes if you need to perform
any operations after the record is created in the database.
When this method is called, object relations are not saved to the database yet.
¶ after_create_saved() methodpublic void after_create_saved()
Called after a new object is saved to the database.
Override this method in your model classes if you need to perform
any operations after the record is created in the database.
When this method is called, object relations are already saved to the database.
¶ after_delete() methodpublic void after_delete()
Called after an existing or new record is deleted from the database.
Override this method in your model classes if you need to perform
any operations after the record is deleted from the database.
¶ after_modify() methodpublic void after_modify(string $operation, string $deferred_session_key)
Called after an existing or new record was modified.
Override this method in your model classes if you need to perform
any operations after the record is modified.
¶ after_save() methodpublic void after_save()
Called after an existing or new record is created or updated in the database.
Override this method in your model classes if you need to perform
any operations after the record is saved to the database.
¶ after_update() methodpublic void after_update()
Called after an existing record is updated in the database.
Override this method in your model classes if you need to perform
any operations after the record is updated in the database.
¶ after_validation() methodpublic void after_validation(string $deferred_session_key=NULL)
Triggered after the model column values are validated.
Override this method in your model classes if you need to perform
any operations after the model is validated.
¶ after_validation_on_create() methodpublic void after_validation_on_create(string $deferred_session_key=NULL)
Triggered after a new model column values are validated.
Override this method in your model classes if you need to perform
any operations after a new model is validated.
¶ after_validation_on_update() methodpublic void after_validation_on_update(string $deferred_session_key=NULL)
Triggered after an existing model column values are validated.
Override this method in your model classes if you need to perform
any operations after an existing model is validated.
¶ before_create() methodpublic void before_create(string $deferred_session_key=NULL)
Called before a new object is saved to the database.
Override this method in your model classes if you need to perform
any operations before the record is created in the database.
¶ before_delete() methodpublic void before_delete(integer $id=NULL)
Called before a record is deleted from the database.
Override this method in your model classes if you need to perform
any operations before the record is deleted from the database. Usually
this method is used for checking whether the object can be deleted.
You can throw an exception in the handler to stop the operation. The following
example demonstrates a typical usage of the method:
public function before_delete($id=null)
{
if ($order_num = $this->orders->count) // Load the number of customer orders from the relation
throw new Phpr_ApplicationException("Error deleting customer. There are $order_num order(s)
belonging to this customer.");
}
¶ before_save() methodpublic void before_save(string $deferred_session_key=NULL)
Called before an existing or new record is created or updated in the database.
Override this method in your model classes if you need to perform
any operations before the record is saved to the database.
¶ before_update() methodpublic void before_update(string $deferred_session_key=NULL)
Called before an existing record is updated in the database.
Override this method in your model classes if you need to perform
any operations before the record is updated in the database.
¶ before_validation() methodpublic void before_validation(string $deferred_session_key=NULL)
Triggered before the model column values are validated.
Override this method in your model classes if you need to perform
any operations before the model is validated.
¶ before_validation_on_create() methodpublic void before_validation_on_create(string $deferred_session_key=NULL)
Triggered before a new model column values are validated.
Override this method in your model classes if you need to perform
any operations before a new model is validated.
¶ before_validation_on_update() methodpublic void before_validation_on_update(string $deferred_session_key=NULL)
Triggered before an existing model column values are validated.
Override this method in your model classes if you need to perform
any operations before an existing model is validated.
¶ collection() methodpublic Db_DataCollection collection()
Executes the find_all() method and returns a collection.
This method simplifies front-end coding.
¶ columnValue() methodpublic string columnValue(string $dbName)
Alias for the displayField() method
¶ define_column() methodpublic Db_ColumnDefinition define_column(string $dbName, string $displayName)
Adds a column definition to the model.
Column definitions determine column labels, validation rules and other properties. The method
returns column definition object object which you can use to configure the column presentation and validation parameters.
¶ define_form_fields() methodpublic void define_form_fields(string $context=NULL)
Defines form fields.
Override this method to define the model's form fields. All column which you add to the form
should be defined with define_columns() method.
Use add_form_field(),
add_form_custom_area(),
add_form_partial(),
and add_form_section()
methods inside this method. Example:
public function define_form_fields($context = null)
{
$this->add_form_field('author_name', 'left');
$this->add_form_field('author_email', 'right');
}
See Also¶ define_multi_relation_column() methodpublic Db_ColumnDefinition define_multi_relation_column(string $columnName, string $relationName, string $displayName, string $valueExpression)
Adds column definition for has_and_belongs_to_many or has_many relation field.
You should define columns for a relation field if you want the field to be displayed in lists or forms. The method
returns a column definition object which you can use to configure the column presentation and validation parameters.
Example:
public $has_and_belongs_to_many = array(
'categories'=>array('class_name'=>'Blog_Category', 'join_table'=>'blog_posts_categories', 'order'=>'name')
);
...
public function define_columns($context = null)
{
$this->define_multi_relation_column('categories', 'categories', 'Categories', '@name');
...
}
¶ define_relation_column() methodpublic Db_ColumnDefinition define_relation_column(string $columnName, string $relationName, string $displayName, string $type, string $valueExpression)
Adds column definition for has_on or belongs_to relation field.
You should define columns for a relation field if you want the field to be displayed in lists or forms. The method
returns column definition object object which you can use to configure the column presentation and validation parameters.
Example:
public $belongs_to = array(
'post'=>array('class_name'=>'Blog_Post', 'foreign_key'=>'post_id')
);
...
public function define_columns($context = null)
{
$this->define_relation_column('post', 'post', 'Post', db_varchar, '@title');
...
}
¶ delete() methodpublic void delete(integer $id=NULL)
Deletes the record from the database.
¶ delete_form_field() methodpublic boolean delete_form_field(string $dbName)
Deletes a form field by its corresponding column name.
This method can be used for removing a form field from an existing model
before its form is rendered.
¶ displayField() methodpublic string displayField(string $dbName, string $media='form')
Returns a formatted column value. The field should be defined with define_column(),
define_relation_column() or
define_multi_relation_column() method.
For relation fields the method uses relation data loaded from database with the model data instead of issuing another SQL query. It makes this method efficient in record lists. By default datetime fields are converted to GMT during saving and displayField() returns value converted back to a time zone specified in TIMEZONE parameter in the configuration file (config.php). You can cancel this behavior by calling dateAsIs() of the column definition object. ¶ find() methodpublic Db_ActiveRecord find(integer $id=NULL, array $include=array(), string $form_context=NULL)
Finds a record by its primary key value.
Note that if the primary key value passed to the method is NULL,
the method returns the first record from the result set.
¶ find_all() methodpublic Db_DataCollection find_all(integer $id=NULL, array $include=array(), string $form_context=NULL)
Finds all records and returns the Db_DataCollection object, containing a list of models.
See Also¶ find_by() methodpublic Db_ActiveRecord find_by(string $field, mixed $value, array $include=array())
Finds a record by a field value.
There is a more usable magic method find_by_[column_name], where column_name is
any database column name. Example:
$usa = Shop_Country::create()->find_by_code('US');¶ find_column_definition() methodpublic Db_ColumnDefinition find_column_definition(string $columnName)
Finds a column definition by the column name.
Columns are defined in define_columns() method.
¶ find_form_field() methodpublic Db_FormFieldDefinition find_form_field(string $dbName)
Finds a form field definition by its corresponding column name.
The form field should be defined with define_form_field() method.
This method can be used for configuring a form field in an existing model
before its form is rendered.
¶ join() methodpublic Db_ActiveRecord join(string $table_name, string $conditions, string $columns='', string $type='left')
Adds a table to the query with JOIN statement.
The following code example loads all manufacturers which have products with name "T-shirt".
$obj = new Shop_Manufacturer();
$obj->join('shop_products', 'shop_products.manufacturer_id = shop_manufacturers.id');
$obj->where('shop_products.name=?', 'T-shirt');
$manufacturers = $obj->find_all();
¶ limit() methodpublic Db_ActiveRecord limit(integer $count=NULL, integer $offset=NULL)
Allows to limit the result of the find_all() method with the specified number of records.
The following example loads 10 newest orders from the database.
$orders = Shop_Order::create()->order('id desc')->limit(10);¶ list_related_records_deferred() methodpublic Db_DataCollection list_related_records_deferred(string $name, string $deferred_session_key)
Returns a list of relation objects, taking into account deferred relations.
Use this method to obtain a list of relation records, before the record is saved to the database.
¶ order() methodpublic Db_ActiveRecord order(string $spec)
Allows to order the result of the find_all() method by a specific table column.
The following example loads 10 newest orders from the database, ordered by identifier.
$orders = Shop_Order::create()->order('id desc')->limit(10);¶ orWhere() methodpublic Db_ActiveRecord orWhere()
Adds OR statement to the where clause, allowing to to limit the result of the find() and find_all() methods with SQL filter.
Pass a SQL WHERE string to the parameter:
$order->where('customer_id is null')->orWhere('customer_id=4')->find_all();$orders = $order->orWhere('customer_id=?', 4)->find_all();¶ paginate() methodpublic Phpr_Pagination paginate(integer $page_index, integer $records_per_page)
Allows to limit the result of the find_all() method with a single page of records.
Call this method before the find_all() method call.
$pagination = $products->paginate(0, 10); See Also¶ requestRowCount() methodpublic integer requestRowCount()
Returns a number of rows which would be returned with find_all() method.
Use this method to obtain the number of records which is going to be returned by a subsequent find_all()
method call.
¶ save() methodpublic Db_ActiveRecord save(array $values=NULL, string $deferred_session_key=NULL)
Saves record to the database.
Depending on whether the model was created or loaded from the database the method
creates or updates a corresponding table record.
The optional $values array can be used to set the record field values.
$customer = Shop_Customer::create()->find(23);
$customer->save(array('first_name'=>'john'));
$customer = Shop_Customer::create()->find(23); $customer->first_name = 'john'; $customer->save(); ¶ where() methodpublic Db_ActiveRecord where()
Allows to limit the result of the find() and find_all() methods with SQL filter.
Pass a SQL WHERE string to the parameter:
$order->where('customer_id is not null')->find_all();$orders = $order->where('customer_id=?', 4)->find_all();¶ define_columns() methodprotected void define_columns(string $context=NULL)
Defines model columns.
Override this method to define columns, references and form fields in your models.
By defining columns you inform the framework which fields from the database table we are going
to use in lists and forms, and what titles these fields should have. Columns are objects of
Db_ColumnDefinition class, which has a number of properties determining how
the column is displayed and validated. You can call model's define_column(),
define_relation_column() and
define_multi_relation_column()
methods inside this method. Example:
public function define_columns($context = null)
{
$this->define_column('title', 'Title')->order('asc')->validation()->fn('trim');
$this->define_multi_relation_column('categories', 'categories', 'Categories', '@name');
}
|
This is the API docs for LemonStand V1, which has been discontinued. LemonStand is now a cloud based platform, available at lemonstand.com.