^Status|Draft|
^Todo|Clearer examples|

====== Models =======


===== What are models? =====
Models are classes designed to work with information given by or asked for by the controller. For example, you have a guestbook, the controller will ask the model to retrieve the last ten entries, the model returns those entries to the controller who passes them on to a view. The controller might also send new entries to the model, update existing ones or even delete some.

Note that Kohana doesn't force you to use models. If you choose not to use them, you are free to do so.




===== Naming models =====

Kohana uses specific rules for the naming of models. These are:
  * Models go into the ''application/models/'' directory.
  * Model filenames are lowercase, **do not** have _model appended to them and should be the singular form of the name.
  * The model class name is capitalized, **does** have _Model appended to it and should be the singular form of the name.
  * For models that use [[libraries:orm|ORM]], there are other, more specific, conventions.

=== Example ===

Suppose that you have a table in the database called ''users'' (which is a plural name). The model that represents the ''users'' table would reside in the file ''application/models/user.php'' and the class would be called ''User_Model'' (which are both singular names).

The file would initially look something like this:

<code php>
<?php defined('SYSPATH') or die('No direct script access.');

class User_Model extends Model {

	public function __construct()
	{
		// load database library into $this->db (can be omitted if not required)
		parent::__construct();
	}

}
</code>
===== Loading models =====
The generally accepted way of loading a Model in Kohana is to do so within your Controller.

For instance, to load the user model (above) from ''application/models/user.php'' add the following to your controller:

<code php>
$user = new User_Model;
$name = $user->get_user_name($id);  // get_user_name is a method defined in User_Model
</code>

=== Inheriting ===
If, for example, you use the Kohana Template_Controller and need access to your model from all descendant controllers, you can add the following to the Template_Controller constructor:
<code php>
$this->user = new User_Model;
</code>

You can then access the user model from any controller that extends the Template_Controller, like this:
<code php>
$name = $this->user->get_user_name($id);  // get_user_name is a method defined in User_Model
</code>


=== Deprecated ===

The following alternative method using the Loader library is **deprecated** in Kohana 2.1 and will no longer be supported in Kohana 2.2.
<code php>
// Model name is called without _Model, case doesn't matter
// Deprecated as of Kohana 2.1
$this->load->model('user');
$name = $this->user->get_user_name($id);
</code>













===== Usage =====

A model might look something like this:
<code php>
class User_Model extends Model {

        public function __construct($id = NULL)
        {
               // load database library into $this->db (can be omitted if not required)
               parent::__construct($id);
        }

	/**
	 * Get information about a user, given their user_id
	 * @param integer the user_id
	 * @return the result object
	 */
	public function get_user($user_id)
	{
		$this->db->where('user_id', $user_id);
		return $this->db->get('users');
	}

	/**
	 * Add a new user. Assumes an auto incrementing user_id in the database.
	 * @param array user data. E.g.,
	 *	array( 'name' => 'test', 'email' => 'test@example.com' )
	 * @return void
	 */
	public function insert_user($data)
	{
		$this->db->insert('users', $data);
	}

	/**
	 * Replace user details.
	 * @param array user data. E.g.,
	 *	array( 'name' => 'test', 'email' => 'test@example.com' )
	 * @return void
	 */
	public function update_user($user_id, $data)
	{
		$this->db->where('user_id', $user_id);
		$this->db->update('users', $data);
	}

}
</code>
Note: When utilizing data from a form always use ''$this->input->post('var_name', TRUE)'' to ensure data is sanitized before using.
[[:libraries:input|Learn more about the Input library.]]


===== Using a database in your model =====
If your model's constructor contains the line ''parent::__construct();'', the default database functionality will be loaded into ''$this->db''. You can use all of the database's functions with the ''$this->db'' object.

You may also specify a [[libraries:database:configuration|database group]] by setting the protected variable ''$db'' in your model.
<code php>
protected $db = 'group_name';
</code>


===== Using a model in your controller =====
Using the example model above, you can integrate this model into your controller as follows:
  - Create an instance of the model in your controller to make it accessible.  This can be done directly in a controller method as ''$user = new User_Model''.  If you want the model accessible from all of your controller methods, create an instance of the model in your controller constructor:   ''$this->user = new User_Model''.
  - If you used the constructor method above, you can now retrieve user information from your database within any of your controller methods with: ''$user = $this->user->get_user(1)''.  The ''$user'' variable now contains a database result set object (for the user with id = 1) that can be passed to your [[:general:views|View]].
  - If you passed the entire ''$user'' variable to your View, you can access specific user data elements within your View in the form ''$user->name''.  See [[:libraries/database/result|Database Library]] for more information.


===== ORM =====
See for more information
  * [[libraries:orm|ORM]]

[[libraries:orm|ORM]] is a special kind of model. Based on its name it will derive for example the table it is a model for, it will also have some basic functions (find($id), save()...) commonly used in a model as well as support for relationships between tables (has_many, belongs_to...). Another aspect of ORM is that it turns a record from a database into an object.