建立模型 - Orm 套件

建立模型

建立模型花费极少时间，惯例是给类别使用 Model_ 前缀 （例如 Model_Article 使用档案名称 article.php） 并因此把它们放在 app/classes/model/， 但你可以自由使用任何你选择的名称。

class Model_Article extends Orm\Model {}

以上方法只适用于 MySQL 和 MySQLi 的驱动，因为它需要从资料库中取回模型特性。 然而，这不是很有效率，因此不鼓励使用这种方式， 因为你始终需要在每个模型多一个额外的查询就为了取回行名。

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

配置

你可以添加静态特性到该模型来配置它。正如我们看到的，没有要求但鼓励设定 $_properties。这些全部可以是 public 和 protected 但可能不是 private。
请注意，所有配置特性都以单一底线前缀， 以预防与你的行名碰撞。

protected static $_table_name

When this isn't set the Model_ prefix is removed from the class name and the class name 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

预设情况下，这设为 array('id')，如果你使用其他行名称或多个主键， 你需要设定此特性。

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 and 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 $_conditions

By default this property does not exist and Model::condition() returns array(), but you can set on the model if you want any conditions defined on every query run. Currently 'order_by' and 'where' conditions are supported.

class Model_Article extends Orm\Model
{
	protected static $_conditions = array(
		'order_by' => array('id' => 'desc'),
		'where' => array(
array('publish_date', '>', 1370721177),
array('published', '=', 1),
		),
	);
}

The order_by condition is only applied if no other order by clause is defined. The where conditions are added using and to any other defined where clauses.

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

模型的相互关联在 关联模型 里有解释。

protected static $_connection

在预设情况下这个特性不存在，且 Model::connection() 回传 null， 但你可以设定它为任何其他配置在 app/config/db.php 的资料库名称。

protected static $_write_connection

If you have a master/slave setup for your database environment, you can use this property to define the connection to use for the write master. If configured, the $_connection property will be used to connect to the read slaves.

By default this property does not exist and Model::connection(true) returns either the configured $_connection, or null, but you can set it to any other database name configured in app/config/db.php.

// 给单一资料库使用的配置
class Model_Article extends Orm\Model
{
	// 'articles_db' 必须被配置在你的 db.php 配置档案
	protected static $_connection = 'articles_db';
}

// 给 master/slave 资料库使用的配置
class Model_Article extends Orm\Model
{
	// 'articles_master_db' 和 'articles_slave_db' 必须被配置在你的 db.php 配置档案
	protected static $_write_connection = 'articles_master_db';
	protected static $_connection = 'articles_slave_db';
}

Note that relations do not work across connections, so when you define your connections in the model, make sure your related models have exactly the same configuration, both for reads and writes!

protected static $_to_array_exclude

If you are writing an API driven application, often you want to limit the columns that are exposed to the API interface. For example, when exposing a user record, you would not want to expose the user's password, login hash or salt.

In your model definition, you can add a list of columns to the to_array_exclude array to exclude them from being exported using to_array().

class Model_User extends Orm\Model
{
	protected static $_to_array_exclude = array(
		'password', 'login_hash', 'salt'	// 排除这些行被导出
	);
}

By default the to_array() method exports both column and relation data loaded in the current model object. Optionally, it allows you to export the custom properties too. Array exclusion works on column names, custom properties and relations, allowing you to exclude properties from all of them.

protected static $_observers

添加观察者在 观察者 里有解释。