07_Bonfire Models

Bonfire Models

Keeping with the MVC spirit, Bonfire uses Models to allow you interact with your database in a simple, consistent manner. By using the BF_Model as the base class for all of your models, you can very quickly setup a simple model capable of finding records, creating new and editing existing records, deleting records, checking if a key/value is unique in this table, counting the results, and more.

BF_Model acts as a middleman layer to between your models and CodeIgniter's standard Model class, working hand-in-hand with ActiveRecord query builder. If you don't need any special queries, your can have a working model in just a handful of lines.

Is it an ORM?

BF_Model is not an ORM. While ORM's have their place, Bonfire does not ship with one included.

A Skeleton Model

To get started with a new model, you can use the following skeleton file:

    class X_model extends BF_Model {
    
        protected $table    = '';
        protected $key      = 'id';
        protected $soft_deletes = FALSE;
        protected $date_format  = 'datetime';
        protected $log_user     = FALSE;
        
        protected $set_created  = TRUE;
        protected $created_field    = 'created_on';
        protected $created_by_field = 'created_by';
        
        protected $set_modified     = FALSE;
        protected $modified_field   = 'modified_on';
        protected $modified_by_field = 'modified_by';
        
          // Observers
        protected $before_insert    = array();
        protected $after_insert     = array();
        protected $before_update    = array();
        protected $after_update     = array();
        protected $before_find      = array();
        protected $after_find       = array();
        protected $before_delete    = array();
        protected $after_delete     = array();
    
        protected $return_type      = 'object';
        protected $protected_attributes = array();
    }

This is the bare minimum needed to take advantage of BF_Model's built-in functions. All variables shown here are set to their default, so you don't need to show them if you are using the default values. Model_name is the name of your class and follows the same rules as CodeIgniter models.

BF_Model supports quite a few ways to customize how your class works with the database.

$table

The var $table should be set to the name of the table in your database. If you database is set to use a prefix (Bonfire defaults to a bf_ prefix), you should leave the prefix off. So a table named bf_users should be entered as users.

$key

The var $key should be the name of the primary key for your table. BF_Model requires that your table has primary key. If it doesn't you should extend Model and will need to write your own methods to interface with the database. The $key is expected to be linked to an INT field.

$soft_deletes

Bonfire uses the concept of soft deletes that will set a flag that an item has been deleted instead of actually deleting the item. This allows you to later restore the user in case the deletion was accidental, or to keep a permanent record of any sensitive information, like transaction records.

To use soft_deletes, your table must have a deleted field that is a TINYINT (1). A value of 0 means the record has not been deleted, while a value of 1 shows that the item has been deleted.

If $soft_deletes == TRUE, Bonfire will automatically update the record to set deleted to a value of 1.

If $soft_deletes == FALSE, the record will be permanently deleted from the database.

$date_format

Determines the type of field that is used to store created and modified dates. The possible values are:

• ‘int’ - A Unix integer timestamp.
• ‘datetime’ Is a MySQL Datetime field. ( YYYY-MM-DD HH:MM:SS )
• ‘date’ is a MySQL Date field. ( YYYY-MM-DD )

While ‘int’ seems to be one of the most common amongst PHP developers, datetime should be at least considered since it makes inspecting your data within the database much easier to interpret, though it does take a little bit more work during the script execution.

$set_created

Bonfire can automatically set your created on dates and times for you, in the format specified through $date_format. To use this, your table must have a created_on field of the proper type.

If $set_created == TRUE, Bonfire will set the created_on field value for you at the time of an insert() call.

$set_modified

Bonfire can automatically set your modified on dates and times for you, in the format specified through $date_format. To use this, your table must have a modified_on field of the proper type.

If $set_created == TRUE, Bonfire will set the created_on field value for you at the time of an insert() call.

$created_field & $modified_field

created_field and modified_field specify the name of the field that the time is inserted into. Defaults to created_on and modified_on.

$log_user

log_user provides a way to keep a small activity trail of actions related to each record. When TRUE, it will populate a field in the record with the user id. This applies to the insert, update and deleted commands, and their related methods, like update_by.

The name of the fields to store the user id in can be set by changing the created_by_field, modified_by_field and deleted_by_field values. They default to created_by, modified_by and deleted_by, respectively.

$escape

When FALSE, the select() method will not try to protect your field names with backticks. This is useful if you need a compound statement.

$db_con

Holds the database connection details for this model only. Can be either a string or an array as per the CodeIgniter manual. This is useful if you have a single model that needs to use a database connection different than the rest, like a logging class.

$return_type

Specifies whether the model returns records as an object or an array. The only valid values here are object or array.

The format can be overridden on a per-call basis using the as_array and as_object methods.

$user = $this->user_model->as_array()->find($id);

$protected_attributes

This is simply a list of keys that will always be removed from the data arrays passed to the insert, update, and similar methods. This is convenient if you like to throw your $_POST arrays directly at the model, but don't want the 'submit' inputs being saved, or for always removing the 'id' if it's passed in.

protected $protected_attributes = array( 'submit', 'id' );

=

Provided Methods

By using the skeleton file, you get a number of methods ready to use on your model. All of these methods can be overriden in your own model if you need to customize them by joining other tables, processing the results before handing off to the controller, etc.

$user = $this->user_model->select(‘id, username, email’)
                         ->where(‘deleted’, 1)
                         ->limit(10,0)
                         ->find_all();

If you need to do additional processing, join tables, etc than you can do that in your model using CodeIgniter’s built-in ActiveRecord commands.

class User_model extends BF_Model {
    public function find_all()
    {
        $this->db->join(...);
        return parent::find_all();
    }
}

find()

The find() method is used to locate a single record based on it's id.

$user = $this->user_model->find($id);

echo $user->username;

Returns an object with the results if found, or FALSE if not found.

find_by()

A convenience method that combines the where() and find() methods. Expects to return a single result, so you should search on a field that will have unique values.

$this->user_model->find_by('email', '[email protected]');

This method can also be called with only a single associative array as the first parameter. This allows you set multiple criteria to search by.

$user = $this->user_model->find( array('email'=>'[email protected]', 'deleted'=>0) );

# SQL: SELECT * FROM `bf_users` WHERE email='[email protected]' AND deleted='0'

This defaults to combining all criteria as "AND" but can be modified by passing the the type into the third parameter:

$user = $this->user_model->find( array('email'=>'[email protected]', 'deleted'=>0), null, 'OR' );

# SQL: SELECT * FROM `bf_users` WHERE email='[email protected]' OR deleted='0'

find_all()

Locates all records in the table.

$this->user_model->find_all();

If you need to modify the search criteria you can use any of the chainable methods.

$users = $this->user_model->where('deleted', 1)
                          ->limit(25)
                          ->find_all();

foreach ($users as $user)
{
    echo $user->username;
}

Returns an array of objects where each object holds the results of a single record.

find_all_by()

Locates all records matching certain criteria. This is a convenience method for using a where() and a find_all() in one command.

$this->user_model->find_all_by('deleted', 1);

Any of the standard options available to a CodeIgniter where() method may be used here.

$this->user_model->find_all_by('deleted', 1);
$this->user_model->find_all_by('deleted !=', 0);
$this->user_model->find_all_by( array('email'=>'[email protected]', 'deleted'=>0) );

Returns an array of objects where each object holds the results of a single record.

insert()

Creates a new record. Will set the created_on field if the model is setup to allow that. The first parameter should be an associative array of field/values to insert.

$user = array(
    'email'     => '[email protected]',
    'username'  => 'darth.vader'
);
$this->user_model->insert($user);

# SQL: INSERT INTO `bf_users` (email, username, created_on) VALUES ('[email protected]', 'darth.vader', 1321645674);

Returns an INT ID of the new record on success, or FALSE on failure.

insert_batch()

Allows for inserting more than one record at a time. Works just like CodeIgniter’s stock method, but handles setting the table name for you.

$data = array(
   array(
      'title' => 'My title' ,
      'name' => 'My Name' ,
      'date' => 'My date'
   ),
   array(
      'title' => 'Another title' ,
      'name' => 'Another Name' ,
      'date' => 'Another date'
   )
);

$this->db->insert_batch('mytable', $data);

update()

Updates an existing record in the database by ID. Will set the correct time for the modified_on field, if the model requires it.

$user = array(
    'email'     => '[email protected]',
    'username'  => 'darth.vader'
);
$this->user_model->update($user_id, $user);

# SQL: UPDATE `bf_users` SET email='[email protected]', username='darth.vader', modified_on=1321645674 WHERE id=1;

Returns a boolean TRUE/FALSE on success/failure.

update_where()

Updates a single record in the database by a key/value pair. Will set the correct time for the modified_on field, if the model requires it.

$user = array(
    'email'     => '[email protected]',
    'username'  => 'darth.vader'
);
$this->user_model->update('is_father', 1, $user);

# SQL: UPDATE `bf_users` SET email='[email protected]', username='darth.vader', modified_on=1321645674 WHERE is_father=1;

update_batch()

Updates multiple records with a single method call.

$data = array( array( 'title' => 'My title' , 'name' => 'My Name 2' , 'date' => 'My date 2' ), array( 'title' => 'Another title' , 'name' => 'Another Name 2' , 'date' => 'Another date 2' ) );

$this->model->update_batch($data, 'title');

The first parameter is an array of values. The second parameter is the where key.

delete()

Deletes a single record from the database. If $soft_deletes are on, then will just set the deleted field to 1. Otherwise, will permanently delete the record from the database.

$this->user_model->delete($user_id);

# SQL w/ soft deletes: UPDATE bf_users SET deleted=1 WHERE id=$user_id;
# SQL w/out soft deletes: DELETE FROM bf_users WHERE id=$user_id;

Returns a boolean TRUE/FALSE on success/failure.

delete_where()

Deletes one or more records that match certain requirements. If $soft_deletes == true, will set the deleted field to 1, otherwise will delete the record permenantly.

The first parameter accepts an array of key/value pairs to form the ‘where’ portion of the query.

$wheres = array(
    ‘active’    => 0,
    ‘last_login’ => ‘< ‘. time()
);
$this->model->delete($wheres);

is_unique()

Checks to see if a given field/value combination would be unique in the table.

$this->user_model->is_unique('email', '[email protected]');

count_all()

Counts all records in the table.

$this->user_model->count_all();

Returns an INT containing the number of results, or FALSE.

count_by()

Counts the number of elements that match the field/value pair.

$this->user_model->count_by('delete', 1);

Returns an INT containing the number of results, or FALSE.

get_field()

A convenience method to return only a single field of the specified row. The first parameter is the ID of the row to search in. The second parameter is the column to return the value of.

$this->user_model->get_field($user_id, 'email');

Returns the value of the row's field, or FALSE.

Return Types

You can temporarily override the type of records returned by the model by using the folliwing commands. This allows you to use objects as a default since they consume less memory, but ask for the results as an array for a single method that you need the extra flexibilty arrays provide.

as_array()

A chainable method that specifies the model should return the results as an array (for single results) or an array of arrays (for multiple rows). This overrides the models $result_type class variable.

as_object()

A chainable method that specifies the model should return the results as an object (for single results) or an array of objects (for multiple rows). This overrides the models $result_type class variable.

as_json()

A chainable method that specifies the model should return the results as a JSON object suitable for returning in AJAX methods. This overrides the models $result_type class variable.

=

Chainable Methods

Thanks to CodeIgniter's ActiveRecord library, it is very simply to modify the BF_Model's methods. This can be done through either chainable methods or by extending methods.

Chainable methods are a feature of PHP 5 and higher that allow you to return the results of one function into another, and to keep this 'chain' of events continuing through several functions. Bonfire duplicates several of the stock ActiveRecord methods in BF_Model to make it simple and elegant to customize your queries.

Bonfire's model supports chaining for most of the ActiveRecord methods available, including:

• select
• select_max
• select_min
• select_avg
• select_sum
• distinct
• from
• join
• where
• or_where
• where_in
• or_where_in
• where_not_in
• or_where_not_in
• like
• not_like
• or_like
• or_not_like
• group_by
• having
• or_having
• limit
• offset
• set

All of these methods accept the same parameters as their CodeIgniter counterparts. These are included for the sole reason of making your syntax more expressive. You can now do things like:

$this->user_model->where('city', 'Detroit')
                 ->or_where('city', 'Cleveland')
                 ->join('tour_dates', 'x on y')
                 ->find_all();

where()

Modifies the query to a specific where condition. Can be used with any of the read-type queries (find, find_all, etc).

The first parameter is the field to match against. The second parameter is the value of the field to find.

Accepts any of the standard CodeIgniter ActiveRecord where statements.

$this->user_model->where('email', '[email protected]');
$this->user_model->where('email !=', '[email protected]');
$this->user_model->where( array('email' => '[email protected]') );

$this->user_model->where('email', '[email protected]')
                 ->find_all();

You can also pass an array of field/value pairs as the first parameter. In this case, the second parameter is ignored.

$wheres = array(
    ‘active’        => 1,
    ‘deleted’   => 0
);
$results = $this->model->where($wheres)->find_all();

Extending Methods

While it is possible to modify the query via the chainable methods any time you need results in your controller, it is highly recommended to extend the model's methods to bring you the results you need. This keeps all of your changes to queries in a single place.

Sometimes, you might want to do some additional processing to the database results before passing it on to the controller. This is another perfect example of when to extend the model's method.

To extend an existing method, you simply create a new method in your model that accepts the same parameters as the original BF_Model method.

// Extend the existing functionality.
public function find($id=null)
{
    $result = parent::find($id);

    if ($result)
    {
        $result->display_name = $this->format_name($result);
    }

    return $result;
}

Modify Query in Controller

You can modify a query in your model for a single use by using CodeIgniter's ActiveRecord commands in your controllers. Since BF_Model uses the ActiveRecord commands, the changes in your controller will affect the results of the next query in your model.

// In your controller.
$this->db->join('other_table', 'link_field = users.id', 'left');
$user = $this->user_model->find($user_id);

Observers

Observers provide a simple and convenient method for your models to change portions of the data at certain execution points within a model’s interaction. This can be very handy for adding in the created_on time before inserting a record, or deleting related records in other tables whenever a user is deleted.

The following events can be observed by your class:

• before_insert
• after_insert
• before_update
• after_update
• before_find
• after_find
• before_delete
• after_delete

These are each arrays that should have the name of the methods to call, in order of priority as the array’s elements.

protected $before_insert = array(‘set_created_on’, ‘another_callback’);

To observe an event and have your methods called you simply add the method name to the definition array and create a new function.

protected function set_created_on($row)
{
    if (!array_key_exists($this->created_field, $row))
    {
        $row[$this->created_field] = $this->set_date();
    }

    return $row;
}

Each observing method must accept a single parameter. Depending on the event triggered, this might be a single INT, or an array of values, etc. Check the function to verify what the payload being passed along is for the event you’re observing.