FuelPHP, a PHP 5.3 Framework Documentation

Creating Models

Creating a model takes little time, the convention is to use the Model_ prefix for the class (eg Model_Article using the filename article.php) and thus place them in app/classes/model/ but you are free to use whatever name you choose.

class Model_Article extends Orm\Model {}

The above only works with the MySQL and MySQLi drivers because it needs to fetch the model properties from the database. It is however not very efficient and thus discouraged to use it this way because you'll always need that one extra query per model just to fetch the columnnames.

class Model_Article extends Orm\Model
{
	protected static $_properties = array('id', 'title', 'contents', 'publish');
}

Configuration

You can add static properties to the Model to configure it. As we've seen there are none required but setting $_properties is encouraged. All these can be both public and protected but may NOT be private.
Note that all configuration properties are prefixed with a single underscore to prevent collisions with your column names.

protected static $_table_name

When this isn't set the Model_ prefix is removed from the classname and the classname is pluralized. Thus "Model_Article" expects table "articles". If you don't follow this convention you can change it by setting the $_table_name property.

class Model_Article extends Orm\Model
{
	protected static $_table_name = 'myarticles';
}

protected static $_primary_key

By default this is set to array('id'), if you use another column name or multiple primary keys you need to set this property.

class Model_Article extends Orm\Model
{
	protected static $_primary_key = array('aid');
}

The primary key must be a real primary key: unique and unchanging. Don't use it for other purposes (like a foreign key in a one-one relation) as well, that won't work as the PK can't be changed. The Orm won't check this, and while it might seem to work at first glance: you'll get into trouble.
It is not required for the PK to be auto_increment (though preferred) and you can specify the PK yourself, but only the first time. Once it's set, it's set.

protected static $_properties

There's already a simple example above of adding all model properties, they can also be configured by using the column name as the key and setting options like type, label & validation.

class Model_Article extends Orm\Model
{
	protected static $_properties = array(
		'id', // both validation & typing observers will ignore the PK
		'name' => array(
			'data_type' => 'varchar',
			'label' => 'Article Name',
			'validation' => array('required', 'min_length' => array(3), 'max_length' => array(20)),
			'form' => array('type' => 'text'),
			'default' => 'New article',
		),
		'gender' => array(
			'data_type' => 'varchar',
			'label' => 'Gender',
			'form' => array('type' => 'select', 'options' => array('m' => 'Male', 'f' => 'Female')),
			'validation' => array('required'),
		),
		'created_at' => array(
			'data_type' => 'int',
			'label' => 'Created At',
			'form' => array(
				'type' => false, // this prevents this field from being rendered on a form
			),
		),
		'updated_at' => array('data_type' => 'int', 'label' => 'Updated At')
	);
}

Form attributes can be passed in the form of an array as shown in the example.

Validation rules can be passed as either just the rule: array('required') or as the rule with an array of params: array('min_length' => array(3)) both are shown in the example above. A full explanation of the Validation class and it's rule can be found under Core.

protected static $_has_one, $_belongs_to, $_has_many, $_many_many, $_many_through

Relating models to each other is explained in Relating Models

protected static $_connection

By default this property does not exist and Model::connection() returns null, but you can set it to any other database name configured in app/config/db.php. Note however that relations don't work across connections.

class Model_Article extends Orm\Model
{
	protected static $_connection = 'articles_database';
}

protected static $_observers

Adding observers is explained in Observers