使用模型Working with Models

模型代表了应用程序中的信息（数据）和处理数据的规则。模型主要用于管理与相应数据库表进行交互的规则。 大多数情况中，在应用程序中，数据库中每个表将对应一个模型。 应用程序中的大部分业务逻辑都将集中在模型里。

A model represents the information (data) of the application and the rules to manipulate that data. Models are primarily used for managing the rules of interaction with a corresponding database table. In most cases, each table in your database will correspond to one model in your application. The bulk of your application’s business logic will be concentrated in the models.

Phalcon\Mvc\Model 是 Phalcon 应用程序中所有模型的基类。它保证了数据库的独立性，基本的 CURD 操作， 高级的查询功能，多表关联等功能。 PhalconMvcModel 不需要直接使用 SQL 语句，因为它的转换方法，会动态的调用相应的数据库引擎进行处理。

Phalcon\Mvc\Model is the base for all models in a Phalcon application. It provides database independence, basic CRUD functionality, advanced finding capabilities, and the ability to relate models to one another, among other services. Phalcon\Mvc\Model avoids the need of having to use SQL statements because it translates methods dynamically to the respective database engine operations.

模型是数据库的高级抽象层。如果您想进行低层次的数据库操作，您可以查看 Phalcon\Db 组件文档。

Models are intended to work on a database high layer of abstraction. If you need to work with databases at a lower level check out the Phalcon\Db component documentation.

创建模型Creating Models

模型是一个继承自 Phalcon\Mvc\Model 的一个类。 它必须放到 models 文件夹。一个模型文件必须包含一个类， 同时它的类名必须符合驼峰命名法：

A model is a class that extends from Phalcon\Mvc\Model. It must be placed in the models directory. A model file must contain a single class; its class name should be in camel case notation:

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
}

上面的例子显示了 “Robots” 模型的实现。 需要注意的是 Robots 继承自 Phalcon\Mvc\Model 。 因此，Robots 模型拥有了大量继承自该组件功能，包括基本的数据库 CRUD (Create, Read, Update, Delete) 操作，数据验证以及复杂的搜索支持，并且可以同时关联多个模型。

The above example shows the implementation of the “Robots” model. Note that the class Robots inherits from Phalcon\Mvc\Model. This component provides a great deal of functionality to models that inherit it, including basic database CRUD (Create, Read, Update, Delete) operations, data validation, as well as sophisticated search support and the ability to relate multiple models with each other.

如果使用 PHP 5.4/5.5 建议在模型中预先定义好所有的列，这样可以减少模型内存的开销以及内存分配。

If you’re using PHP 5.4/5.5 it is recommended you declare each column that makes part of the model in order to save memory and reduce the memory allocation.

默认情况下，模型 “Robots” 对应的是数据库表 “robots”， 如果想映射到其他数据库表，可以使用 getSource() 方法：

By default, the model “Robots” will refer to the table “robots”. If you want to manually specify another name for the mapping table, you can use the getSource() method:

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    public function getSource()
    {
        return "the_robots";
    }
}

模型 Robots 现在映射到了 “the_robots” 表。initialize() 方法可以帮助在模型中建立自定义行为，例如指定不同的数据库表。 initialize() 方法在请求期间只被调用一次。

The model Robots now maps to “the_robots” table. The initialize() method aids in setting up the model with a custom behavior i.e. a different table. The initialize() method is only called once during the request.

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    public function initialize()
    {
        $this->setSource("the_robots");
    }
}

initialize() 方法在请求期间仅会被调用一次，目的是为应用中所有该模型的实例进行初始化。如果需要为每一个实例在创建的时候单独进行初始化， 可以使用 ‘onConstruct’ 事件：

The initialize() method is only called once during the request, it’s intended to perform initializations that apply for all instances of the model created within the application. If you want to perform initialization tasks for every instance created you can ‘onConstruct’:

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    public function onConstruct()
    {
        //...
    }
}

公共属性对比设置与取值 Setters/GettersPublic properties vs. Setters/Getters

模型可以通过公共属性的方式实现，意味着模型的所有属性在实例化该模型的地方可以无限制的读取和更新。

Models can be implemented with properties of public scope, meaning that each property can be read/updated from any part of the code that has instantiated that model class without any restrictions:

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    public $id;
    public $name;
    public $price;
}

通过使用 getters/setters 方法，可以控制哪些属性可以公开访问，并且对属性值执行不同的形式的转换，同时可以保存在模型中的数据添加相应的验证规则。

By using getters and setters you can control which properties are visible publicly perform various transformations to the data (which would be impossible otherwise) and also add validation rules to the data stored in the object:

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    protected $id;
    protected $name;
    protected $price;
    public function getId()
    {
        return $this->id;
    }
    public function setName($name)
    {
        //The name is too short?
        if (strlen($name) < 10) {
            throw new \InvalidArgumentException('The name is too short');
        }
        $this->name = $name;
    }
    public function getName()
    {
        return $this->name;
    }
    public function setPrice($price)
    {
        //Negative prices aren't allowed
        if ($price < 0) {
            throw new \InvalidArgumentException('Price can\'t be negative');
        }
        $this->price = $price;
    }
    public function getPrice()
    {
        //Convert the value to double before be used
        return (double) $this->price;
    }
}

公共属性的方式可以在开发中降低复杂度。而 getters/setters 的实现方式可以显著的增强应用的可测试性、扩展性和可维护性。 开发人员可以自己决定哪一种策略更加适合自己开发的应用。ORM同时兼容这两种方法。

Public properties provide less complexity in development. However getters/setters can heavily increase the testability, extensibility and maintainability of applications. Developers can decide which strategy is more appropriate for the application they are creating. The ORM is compatible with both schemes of defining properties.

模型放入命名空间Models in Namespaces

命名空间可以用来避免类名的冲突。ORM通过类名来映射相应的表名。比如 ‘Robots’：

Namespaces can be used to avoid class name collision. The mapped table is taken from the class name, in this case ‘Robots’:

<?php
namespace Store\Toys;
use Phalcon\Mvc\Model;
class Robots extends Model
{
}

理解记录对象Understanding Records To Objects

每个模型的实例对应一条数据表中的记录。可以方便的通过读取对象的属性来访问相应的数据。比如， 一个表 “robots” 有如下数据：

Every instance of a model represents a row in the table. You can easily access record data by reading object properties. For example, for a table “robots” with the records:

mysql> select * from robots;
+----+------------+------------+------+
| id | name       | type       | year |
+----+------------+------------+------+
|  1 | Robotina   | mechanical | 1972 |
|  2 | Astro Boy  | mechanical | 1952 |
|  3 | Terminator | cyborg     | 2029 |
+----+------------+------------+------+
3 rows in set (0.00 sec)

你可以通过主键找到某一条记录并且打印它的名称：

You could find a certain record by its primary key and then print its name:

<?php
// Find record with id = 3
$robot = Robots::findFirst(3);
// Prints "Terminator"
echo $robot->name;

一旦记录被加载到内存中之后，你可以修改它的数据并保存所做的修改：

Once the record is in memory, you can make modifications to its data and then save changes:

<?php
$robot       = Robots::findFirst(3);
$robot->name = "RoboCop";
$robot->save();

如上所示，不需要写任何SQL语句。 Phalcon\Mvc\Model 为web应用提供了高层数据库抽象。

As you can see, there is no need to use raw SQL statements. Phalcon\Mvc\Model provides high database abstraction for web applications.

查找记录Finding Records

Phalcon\Mvc\Model 为数据查询提供了多种方法。下面的例子将演示如何从一个模型中查找一条或者多条记录：

Phalcon\Mvc\Model also offers several methods for querying records. The following examples will show you how to query one or more records from a model:

<?php
// How many robots are there?
$robots = Robots::find();
echo "There are ", count($robots), "\n";
// How many mechanical robots are there?
$robots = Robots::find("type = 'mechanical'");
echo "There are ", count($robots), "\n";
// Get and print virtual robots ordered by name
$robots = Robots::find(array(
    "type = 'virtual'",
    "order" => "name"
));
foreach ($robots as $robot) {
    echo $robot->name, "\n";
}
// Get first 100 virtual robots ordered by name
$robots = Robots::find(array(
    "type = 'virtual'",
    "order" => "name",
    "limit" => 100
));
foreach ($robots as $robot) {
   echo $robot->name, "\n";
}

如果想通过额外的数据（用户输入数据）查询记录必须要使用`Binding Parameters`_。

If you want find record by external data (such as user input) or variable data you must use `Binding Parameters`_.

你可以使用 findFirst() 方法获取第一条符合查询条件的结果：

You could also use the findFirst() method to get only the first record matching the given criteria:

<?php
// What's the first robot in robots table?
$robot = Robots::findFirst();
echo "The robot name is ", $robot->name, "\n";
// What's the first mechanical robot in robots table?
$robot = Robots::findFirst("type = 'mechanical'");
echo "The first mechanical robot name is ", $robot->name, "\n";
// Get first virtual robot ordered by name
$robot = Robots::findFirst(array("type = 'virtual'", "order" => "name"));
echo "The first virtual robot name is ", $robot->name, "\n";

find() 和 findFirst() 方法都接受关联数组作为查询条件：

Both find() and findFirst() methods accept an associative array specifying the search criteria:

<?php
$robot = Robots::findFirst(array(
    "type = 'virtual'",
    "order" => "name DESC",
    "limit" => 30
));
$robots = Robots::find(array(
    "conditions" => "type = ?1",
    "bind"       => array(1 => "virtual")
));

可用的查询选项如下

The available query options are:

如果你愿意，除了使用数组作为查询参数外，还可以通过一种面向对象的方式来创建查询：

If you prefer, there is also available a way to create queries in an object-oriented way, instead of using an array of parameters:

<?php
$robots = Robots::query()
    ->where("type = :type:")
    ->andWhere("year < 2000")
    ->bind(array("type" => "mechanical"))
    ->order("name")
    ->execute();

静态方法 query() 返回一个对IDE自动完成友好的 :doc:`Phalcon\Mvc\Model\Criteria <../api/Phalcon_Mvc_Model_Criteria>`对象。

The static method query() returns a Phalcon\Mvc\Model\Criteria object that is friendly with IDE autocompleters.

所有查询在内部都以 PHQL 查询的方式处理。PHQL是一个高层的、面向对象的类SQL语言。通过PHQL语言你可以使用更多的比如join其他模型、定义分组、添加聚集等特性。

All the queries are internally handled as PHQL queries. PHQL is a high-level, object-oriented and SQL-like language. This language provide you more features to perform queries like joining other models, define groupings, add aggregations etc.

最后，还有一个 findFirstBy<property-name>() 方法。这个方法扩展了前面提及的 “findFirst()” 方法。它允许您利用方法名中的属性名称，通过将要搜索的该字段的内容作为参数传给它，来快速从一个表执行检索操作。

Lastly, there is the findFirstBy<property-name>() method. This method expands on the “findFirst()” method mentioned earlier. It allows you to quickly perform a retrieval from a table by using the property name in the method itself and passing it a parameter that contains the data you want to search for in that column.

还是用上面用过的 Robots 模型来举例说明：

An example is in order, so taking our Robots model mentioned earlier :

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    public $id;
    public $name;
    public $price;
}

我们这里有3个属性：$id, $name 和 $price。因此，我们以想要查询第一个名称为 ‘Terminator’ 的记录为例，可以这样写：

We have three properties to work with here. $id, $name and $price. So, let’s say you want to retrieve the first record in the table with the name ‘Terminator’. This could be written like so :

<?php
$name  = "Terminator";
$robot = Robots::findFirstByName($name);
if($robot){
    $this->flash->success("The first robot with the name " . $name . " cost " . $robot->price ".");
}else{
    $this->flash->error("There were no robots found in our table with the name " . $name ".");
}

请注意我们在方法调用中用的是 ‘Name’，并向它传递了变量 $name，$name 的值就是我们想要找的记录的名称。另外注意，当我们的查询找到了符合的记录后，这个记录的其他属性也都是可用的。

Notice that we used ‘Name’ in the method call and passed the variable $name to it, which contains the name we are looking for in our table. Notice also that when we find a match with our query, all the other properties are available to us as well.

模型结果集Model Resultsets

findFirst() 方法直接返回一个被调用对象的实例（如果有结果返回的话），而 find() 方法返回一个 Phalcon\Mvc\Model\Resultset\Simple 对象。这个对象也封装进了所有结果集的功能，比如遍历、查找特定的记录、统计等等。

While findFirst() returns directly an instance of the called class (when there is data to be returned), the find() method returns a Phalcon\Mvc\Model\Resultset\Simple. This is an object that encapsulates all the functionality a resultset has like traversing, seeking specific records, counting, etc.

这些对象比一般数组功能更强大。最大的特点是 Phalcon\Mvc\Model\Resultset 每时每刻只有一个结果在内存中。这对操作大数据量时的内存管理相当有帮助。

These objects are more powerful than standard arrays. One of the greatest features of the Phalcon\Mvc\Model\Resultset is that at any time there is only one record in memory. This greatly helps in memory management especially when working with large amounts of data.

<?php
// Get all robots
$robots = Robots::find();
// Traversing with a foreach
foreach ($robots as $robot) {
    echo $robot->name, "\n";
}
// Traversing with a while
$robots->rewind();
while ($robots->valid()) {
    $robot = $robots->current();
    echo $robot->name, "\n";
    $robots->next();
}
// Count the resultset
echo count($robots);
// Alternative way to count the resultset
echo $robots->count();
// Move the internal cursor to the third robot
$robots->seek(2);
$robot = $robots->current();
// Access a robot by its position in the resultset
$robot = $robots[5];
// Check if there is a record in certain position
if (isset($robots[3])) {
   $robot = $robots[3];
}
// Get the first record in the resultset
$robot = $robots->getFirst();
// Get the last record
$robot = $robots->getLast();

Phalcon 的结果集模拟了可滚动的游标，你可以通过位置，或者内部指针去访问任何一条特定的记录。注意有一些数据库系统不支持滚动游标，这就使得查询会被重复执行， 以便回放光标到最开始的位置，然后获得相应的记录。类似地，如果多次遍历结果集，那么必须执行相同的查询次数。

Phalcon’s resultsets emulate scrollable cursors, you can get any row just by accessing its position, or seeking the internal pointer to a specific position. Note that some database systems don’t support scrollable cursors, this forces to re-execute the query in order to rewind the cursor to the beginning and obtain the record at the requested position. Similarly, if a resultset is traversed several times, the query must be executed the same number of times.

将大数据量的查询结果存储在内存会消耗很多资源，正因为如此，分成每32行一块从数据库中获得结果集，以减少重复执行查询请求的次数，在一些情况下也节省内存。

Storing large query results in memory could consume many resources, because of this, resultsets are obtained from the database in chunks of 32 rows reducing the need for re-execute the request in several cases also saving memory.

注意结果集可以序列化后保存在一个后端缓存里面。 Phalcon\Cache 将从数据库检索到的所有数据以一个数组的方式保存，因此在这样执行的地方会消耗更多的内存。

Note that resultsets can be serialized and stored in a cache backend. Phalcon\Cache can help with that task. However, serializing data causes Phalcon\Mvc\Model to retrieve all the data from the database in an array, thus consuming more memory while this process takes place.

<?php
// Query all records from model parts
$parts = Parts::find();
// Store the resultset into a file
file_put_contents("cache.txt", serialize($parts));
// Get parts from file
$parts = unserialize(file_get_contents("cache.txt"));
// Traverse the parts
foreach ($parts as $part) {
   echo $part->id;
}

过滤结果集Filtering Resultsets

过滤数据最有效的方法是设置一些查询条件，数据库会利用表的索引快速返回数据。Phalcon 额外的允许你通过任何数据库不支持的方式过滤数据。

The most efficient way to filter data is setting some search criteria, databases will use indexes set on tables to return data faster. Phalcon additionally allows you to filter the data using PHP using any resource that is not available in the database:

<?php
$customers = Customers::find()->filter(function($customer) {
    //Return only customers with a valid e-mail
    if (filter_var($customer->email, FILTER_VALIDATE_EMAIL)) {
        return $customer;
    }
});

绑定参数Binding Parameters

在 Phalcon\Mvc\Model 中也支持绑定参数。即使使用绑定参数对性能有一点很小的影响，还是强烈建议您使用这种方法，以消除代码受SQL注入攻击的可能性。 绑定参数支持字符串和整数占位符。实现方法如下：

Bound parameters are also supported in Phalcon\Mvc\Model. Although there is a minimal performance impact by using bound parameters, you are encouraged to use this methodology so as to eliminate the possibility of your code being subject to SQL injection attacks. Both string and integer placeholders are supported. Binding parameters can simply be achieved as follows:

<?php
// Query robots binding parameters with string placeholders
$conditions = "name = :name: AND type = :type:";
//Parameters whose keys are the same as placeholders
$parameters = array(
    "name" => "Robotina",
    "type" => "maid"
);
//Perform the query
$robots = Robots::find(array(
    $conditions,
    "bind" => $parameters
));
// Query robots binding parameters with integer placeholders
$conditions = "name = ?1 AND type = ?2";
$parameters = array(1 => "Robotina", 2 => "maid");
$robots     = Robots::find(array(
    $conditions,
    "bind" => $parameters
));
// Query robots binding parameters with both string and integer placeholders
$conditions = "name = :name: AND type = ?1";
//Parameters whose keys are the same as placeholders
$parameters = array(
    "name" => "Robotina",
    1      => "maid"
);
//Perform the query
$robots = Robots::find(array(
    $conditions,
    "bind" => $parameters
));

当使用数字占位符,您需要定义它们为整数即1或2。使用“1”或“2”被认为是字符串而不是数字,所以占位符不能成功地替换了。

When using numeric placeholders, you will need to define them as integers i.e. 1 or 2. In this case “1” or “2” are considered strings and not numbers, so the placeholder could not be successfully replaced.

使用PDO_字符串会被自动转义。这个函数考虑了连接字符集,因此推荐在数据库中的连接参数或配置中定义正确的字符集,定义一个错误的字符集将会在存储或检索数据产生错误的结果。

Strings are automatically escaped using PDO. This function takes into account the connection charset, so its recommended to define the correct charset in the connection parameters or in the database configuration, as a wrong charset will produce undesired effects when storing or retrieving data.

另外你可以设置参数“bindTypes”,这个可以根据参数类型进行绑定:

Additionally you can set the parameter “bindTypes”, this allows defining how the parameters should be bound according to its data type:

<?php
use Phalcon\Db\Column;
//Bind parameters
$parameters = array(
    "name" => "Robotina",
    "year" => 2008
);
//Casting Types
$types = array(
    "name" => Column::BIND_PARAM_STR,
    "year" => Column::BIND_PARAM_INT
);
// Query robots binding parameters with string placeholders
$robots = Robots::find(array(
    "name = :name: AND year = :year:",
    "bind"      => $parameters,
    "bindTypes" => $types
));

因为默认绑定类型为\Phalcon\Db\Column::BIND_PARAM_STR,所以如果所有列的类型都是字符就不需要再指定“bindTypes”参数。

Since the default bind-type is \Phalcon\Db\Column::BIND_PARAM_STR, there is no need to specify the “bindTypes” parameter if all of the columns are of that type.

绑定参数可用于所有查询方法,如find(),findFirst(),count(),sum(),average()等。

Bound parameters are available for all query methods such as find() and findFirst() but also the calculation methods like count(), sum(), average() etc.

初始化/准备获取记录Initializing/Preparing fetched records

普通的流程是从数据库获取数据并处理后供程序后续使用。但是我们也可以在数据模型中实现’afterFetch’这个方法，它将在实例执行后立刻被调用被分配相应的数据:

May be the case that after obtaining a record from the database is necessary to initialise the data before being used by the rest of the application. You can implement the method ‘afterFetch’ in a model, this event will be executed just after create the instance and assign the data to it:

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    public $id;
    public $name;
    public $status;
    public function beforeSave()
    {
        //Convert the array into a string
        $this->status = join(',', $this->status);
    }
    public function afterFetch()
    {
        //Convert the string to an array
        $this->status = explode(',', $this->status);
    }
}

如果公共属性和getter/setter一块使用,当访问这些属性的时候就可以完成初始化:

If you use getters/setters instead of/or together with public properties, you can initialize the field once it is accessed:

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    public $id;
    public $name;
    public $status;
    public function getStatus()
    {
        return explode(',', $this->status);
    }
}

模型关系Relationships between Models

有四种类型的关系:一对一,一对多,多对一和多对多。关系可能是单向或双向,每个可以是简单的(一个对一个模型)或更复杂的(模型)的组合。模型管理器管理这些关系的外键约束,这些定义保证了引用的完整性，让我们容易和快速访问一个模型的相关记录。通过关系的实现, 很容易以统一的方式从相互关联的模型中访问每一条记录。

There are four types of relationships: one-on-one, one-to-many, many-to-one and many-to-many. The relationship may be unidirectional or bidirectional, and each can be simple (a one to one model) or more complex (a combination of models). The model manager manages foreign key constraints for these relationships, the definition of these helps referential integrity as well as easy and fast access of related records to a model. Through the implementation of relations, it is easy to access data in related models from each record in a uniform way.

单项关系Unidirectional relationships

Unidirectional relations are those that are generated in relation to one another but not vice versa.

双向关系Bidirectional relations

The bidirectional relations build relationships in both models and each model defines the inverse relationship of the other.

定义关系Defining relationships

在Phalcon中关系必须在模型的initialize()中定义。belongsTo(),hasOne(),hasMany()和hasManyToMany()定义了从当前模型中一个或多个字段之间的关系到另一个模型中。上述每种方法都需要三个参数:本地字段，引用模型,引用字段。

In Phalcon, relationships must be defined in the initialize() method of a model. The methods belongsTo(), hasOne(), hasMany() and hasManyToMany() define the relationship between one or more fields from the current model to fields in another model. Each of these methods requires 3 parameters: local fields, referenced model, referenced fields.

下面是作为我们演示关系的例子的三个表:

The following schema shows 3 tables whose relations will serve us as an example regarding relationships:

CREATE TABLE `robots` (
    `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
    `name` varchar(70) NOT NULL,
    `type` varchar(32) NOT NULL,
    `year` int(11) NOT NULL,
    PRIMARY KEY (`id`)
);
CREATE TABLE `robots_parts` (
    `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
    `robots_id` int(10) NOT NULL,
    `parts_id` int(10) NOT NULL,
    `created_at` DATE NOT NULL,
    PRIMARY KEY (`id`),
    KEY `robots_id` (`robots_id`),
    KEY `parts_id` (`parts_id`)
);
CREATE TABLE `parts` (
    `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
    `name` varchar(70) NOT NULL,
    PRIMARY KEY (`id`)
);

• The model “Robots” has many “RobotsParts”.
• The model “Parts” has many “RobotsParts”.
• The model “RobotsParts” belongs to both “Robots” and “Parts” models as a many-to-one relation.
• The model “Robots” has a relation many-to-many to “Parts” through “RobotsParts”

看下面的EER图更加直观：

Check the EER diagram to understand better the relations:

模型和之间的关系实现如下：

The models with their relations could be implemented as follows:

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    public $id;
    public $name;
    public function initialize()
    {
        $this->hasMany("id", "RobotsParts", "robots_id");
    }
}

<?php
use Phalcon\Mvc\Model;
class Parts extends Model
{
    public $id;
    public $name;
    public function initialize()
    {
        $this->hasMany("id", "RobotsParts", "parts_id");
    }
}

<?php
use Phalcon\Mvc\Model;
class RobotsParts extends Model
{
    public $id;
    public $robots_id;
    public $parts_id;
    public function initialize()
    {
        $this->belongsTo("robots_id", "Robots", "id");
        $this->belongsTo("parts_id", "Parts", "id");
    }
}

第一个参数表示本地模型中字段关系;第二个参数表示引用模型的名称，第三个参数是引用模型的字段名。你也可以使用数组来定义多个字段的关系。

The first parameter indicates the field of the local model used in the relationship; the second indicates the name of the referenced model and the third the field name in the referenced model. You could also use arrays to define multiple fields in the relationship.

多对多的关系需要3模型并且定义关系中涉及到的属性:

Many to many relationships require 3 models and define the attributes involved in the relationship:

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    public $id;
    public $name;
    public function initialize()
    {
        $this->hasManyToMany(
            "id",
            "RobotsParts",
            "robots_id", "parts_id",
            "Parts",
            "id"
        );
    }
}

使用关系Taking advantage of relationships

当显式地定义模型之间的关系,它很容易为一个特定的记录找到相关的记录。

When explicitly defining the relationships between models, it is easy to find related records for a particular record.

<?php
$robot = Robots::findFirst(2);
foreach ($robot->robotsParts as $robotPart) {
    echo $robotPart->parts->name, "\n";
}

Phalcon使用魔术方法__set/__get /__call存储或检索使用了关系的相关数据。

Phalcon uses the magic methods __set/__get/__call to store or retrieve related data using relationships.

通过访问一个名称相同的关系中的属性将检索所有相关记录。

By accessing an attribute with the same name as the relationship will retrieve all its related record(s).

<?php
$robot = Robots::findFirst();
$robotsParts = $robot->robotsParts; // all the related records in RobotsParts

同样可以使用getter

Also, you can use a magic getter:

<?php
$robot = Robots::findFirst();
$robotsParts = $robot->getRobotsParts(); // all the related records in RobotsParts
$robotsParts = $robot->getRobotsParts(array('limit' => 5)); // passing parameters

如果调用一个有get前缀的方法:doc:Phalcon\Mvc\Model <../api/Phalcon_Mvc_Model> 会返回一个findFirst()/find() 结果，下面的示例对比了使用魔术方法和不使用去获取数据：

If the called method has a “get” prefix Phalcon\Mvc\Model will return a findFirst()/find() result. The following example compares retrieving related results with using magic methods and without:

<?php
$robot       = Robots::findFirst(2);
// Robots model has a 1-n (hasMany)
// relationship to RobotsParts then
$robotsParts = $robot->robotsParts;
// Only parts that match conditions
$robotsParts = $robot->getRobotsParts("created_at = '2012-03-15'");
// Or using bound parameters
$robotsParts = $robot->getRobotsParts(array(
    "created_at = :date:",
    "bind" => array("date" => "2012-03-15")
));
$robotPart   = RobotsParts::findFirst(1);
// RobotsParts model has a n-1 (belongsTo)
// relationship to RobotsParts then
$robot = $robotPart->robots;

手动获取相关记录

Getting related records manually:

<?php
$robot       = Robots::findFirst(2);
// Robots model has a 1-n (hasMany)
// relationship to RobotsParts, then
$robotsParts = RobotsParts::find("robots_id = '" . $robot->id . "'");
// Only parts that match conditions
$robotsParts = RobotsParts::find(
    "robots_id = '" . $robot->id . "' AND created_at = '2012-03-15'"
);
$robotPart   = RobotsParts::findFirst(1);
// RobotsParts model has a n-1 (belongsTo)
// relationship to RobotsParts then
$robot = Robots::findFirst("id = '" . $robotPart->robots_id . "'");

前缀用于find()/findFirst()相关记录。根据关系类型决定使用find还是findFirst

The prefix “get” is used to find()/findFirst() related records. Depending on the type of relation it will use ‘find’ or ‘findFirst’:

还可以使用“count”前缀返回一个表示相关记录的统计整数:

You can also use “count” prefix to return an integer denoting the count of the related records:

<?php
$robot = Robots::findFirst(2);
echo "The robot has ", $robot->countRobotsParts(), " parts\n";

关系别名Aliasing Relationships

为了解释别名如何使用，让我们看下面例子：

To explain better how aliases work, let’s check the following example:

表“robots_similar”定义了类似机器人的信息:

Table “robots_similar” has the function to define what robots are similar to others:

mysql> desc robots_similar;
+-------------------+------------------+------+-----+---------+----------------+
| Field             | Type             | Null | Key | Default | Extra          |
+-------------------+------------------+------+-----+---------+----------------+
| id                | int(10) unsigned | NO   | PRI | NULL    | auto_increment |
| robots_id         | int(10) unsigned | NO   | MUL | NULL    |                |
| similar_robots_id | int(10) unsigned | NO   |     | NULL    |                |
+-------------------+------------------+------+-----+---------+----------------+
3 rows in set (0.00 sec)

robots_id表和similar_robots_id表都和Robots模型有关系：

Both “robots_id” and “similar_robots_id” have a relation to the model Robots:

定义他们之前关系的数据模型如下所示：

A model that maps this table and its relationships is the following:

<?php
class RobotsSimilar extends Phalcon\Mvc\Model
{
    public function initialize()
    {
        $this->belongsTo('robots_id', 'Robots', 'id');
        $this->belongsTo('similar_robots_id', 'Robots', 'id');
    }
}

因为他们的关系都指向了同一个数据模型(Robots)，获取关联数据就会不清楚：

Since both relations point to the same model (Robots), obtain the records related to the relationship could not be clear:

<?php
$robotsSimilar = RobotsSimilar::findFirst();
//Returns the related record based on the column (robots_id)
//Also as is a belongsTo it's only returning one record
//but the name 'getRobots' seems to imply that return more than one
$robot = $robotsSimilar->getRobots();
//but, how to get the related record based on the column (similar_robots_id)
//if both relationships have the same name?

可以使用别名重命名关系，这样就解决了这个问题：

The aliases allow us to rename both relationships to solve these problems:

<?php
use Phalcon\Mvc\Model;
class RobotsSimilar extends Model
{
    public function initialize()
    {
        $this->belongsTo('robots_id', 'Robots', 'id', array(
            'alias' => 'Robot'
        ));
        $this->belongsTo('similar_robots_id', 'Robots', 'id', array(
            'alias' => 'SimilarRobot'
        ));
    }
}

使用别名可以轻松的获取相关数据：

With the aliasing we can get the related records easily:

<?php
$robotsSimilar = RobotsSimilar::findFirst();
//Returns the related record based on the column (robots_id)
$robot = $robotsSimilar->getRobot();
$robot = $robotsSimilar->robot;
//Returns the related record based on the column (similar_robots_id)
$similarRobot = $robotsSimilar->getSimilarRobot();
$similarRobot = $robotsSimilar->similarRobot;

魔术方法 Getters 对比显示方法Magic Getters vs. Explicit methods

大多数IDE和编辑器有自动提示完成代码的功能，但是使用魔法getter方法时不能推断出正确的类型, 而不是使用魔法的getter方法我们可以显式地定义这些方法和相应的docblocks帮助IDE生成更好的自动提示完成代码:

Most IDEs and editors with auto-completion capabilities can not infer the correct types when using magic getters, instead of use the magic getters you can optionally define those methods explicitly with the corresponding docblocks helping the IDE to produce a better auto-completion:

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    public $id;
    public $name;
    public function initialize()
    {
        $this->hasMany("id", "RobotsParts", "robots_id");
    }
    /**
     * Return the related "robots parts"
     *
     * @return \RobotsParts[]
     */
    public function getRobotsParts($parameters=null)
    {
        return $this->getRelated('RobotsParts', $parameters);
    }
}

虚拟外键Virtual Foreign Keys

默认情况下,不像数据库外键的关系那样,如果插入/更新一个无效值到相关模型中,Phalcon不会产生一个验证消息。在定义一个关系的时候可以通过添加第四个参数修改这个行为。

By default, relationships do not act like database foreign keys, that is, if you try to insert/update a value without having a valid value in the referenced model, Phalcon will not produce a validation message. You can modify this behavior by adding a fourth parameter when defining a relationship.

修改下RobotsPart模型来演示这个功能:

The RobotsPart model can be changed to demonstrate this feature:

<?php
use Phalcon\Mvc\Model;
class RobotsParts extends Model
{
    public $id;
    public $robots_id;
    public $parts_id;
    public function initialize()
    {
        $this->belongsTo("robots_id", "Robots", "id", array(
            "foreignKey" => true
        ));
        $this->belongsTo("parts_id", "Parts", "id", array(
            "foreignKey" => array(
                "message" => "The part_id does not exist on the Parts model"
            )
        ));
    }
}

如果改变一个belongsTo()作为外键的关系,在进行插入/更新相关模型操作时它将验证这些字段值是否有效。类似地,如果一个hasMany()/hasOne()被加了外键约束，它将验证记录不能被删除，如果记录还在存在一个相关模型中。

If you alter a belongsTo() relationship to act as foreign key, it will validate that the values inserted/updated on those fields have a valid value on the referenced model. Similarly, if a hasMany()/hasOne() is altered it will validate that the records cannot be deleted if that record is used on a referenced model.

<?php
use Phalcon\Mvc\Model;
class Parts extends Model
{
    public function initialize()
    {
        $this->hasMany("id", "RobotsParts", "parts_id", array(
            "foreignKey" => array(
                "message" => "The part cannot be deleted because other robots are using it"
            )
        ));
    }
}

级联与限制动作Cascade/Restrict actions

默认关系作为虚拟外键限制创建/更新/删除记录来保持数据的完整性:

Relationships that act as virtual foreign keys by default restrict the creation/update/deletion of records to maintain the integrity of data:

<?php
namespace Store\Models;
use Phalcon\Mvc\Model;
use Phalcon\Mvc\Model\Relation;
class Robots extends Model
{
    public $id;
    public $name;
    public function initialize()
    {
        $this->hasMany('id', 'Store\\Models\Parts', 'robots_id', array(
            'foreignKey' => array(
                'action' => Relation::ACTION_CASCADE
            )
        ));
    }
}

上面的代码设置如果主记录(robot)被删除则删除所有被引用的记录(parts)。

The above code set up to delete all the referenced records (parts) if the master record (robot) is deleted.

生成运算Generating Calculations

Phalcon\Mvc\Model 计算或者统计函数像是 COUNT, SUM, MAX, MIN or AVG可以直接使用。

Calculations (or aggregations) are helpers for commonly used functions of database systems such as COUNT, SUM, MAX, MIN or AVG. Phalcon\Mvc\Model allows to use these functions directly from the exposed methods.

Count examples:

<?php
// How many employees are?
$rowcount = Employees::count();
// How many different areas are assigned to employees?
$rowcount = Employees::count(array("distinct" => "area"));
// How many employees are in the Testing area?
$rowcount = Employees::count("area = 'Testing'");
// Count employees grouping results by their area
$group = Employees::count(array("group" => "area"));
foreach ($group as $row) {
   echo "There are ", $row->rowcount, " in ", $row->area;
}
// Count employees grouping by their area and ordering the result by count
$group = Employees::count(array(
    "group" => "area",
    "order" => "rowcount"
));
// Avoid SQL injections using bound parameters
$group = Employees::count(array(
    "type > ?0",
    "bind" => array($type)
));

求和例子：

Sum examples:

<?php
// How much are the salaries of all employees?
$total = Employees::sum(array("column" => "salary"));
// How much are the salaries of all employees in the Sales area?
$total = Employees::sum(array(
    "column"     => "salary",
    "conditions" => "area = 'Sales'"
));
// Generate a grouping of the salaries of each area
$group = Employees::sum(array(
    "column" => "salary",
    "group"  => "area"
));
foreach ($group as $row) {
   echo "The sum of salaries of the ", $row->area, " is ", $row->sumatory;
}
// Generate a grouping of the salaries of each area ordering
// salaries from higher to lower
$group = Employees::sum(array(
    "column" => "salary",
    "group"  => "area",
    "order"  => "sumatory DESC"
));
// Avoid SQL injections using bound parameters
$group = Employees::sum(array(
    "conditions" => "area > ?0",
    "bind" => array($area)
));

求平均例子：

Average examples:

<?php
// What is the average salary for all employees?
$average = Employees::average(array("column" => "salary"));
// What is the average salary for the Sales's area employees?
$average = Employees::average(array(
    "column"     => "salary",
    "conditions" => "area = 'Sales'"
));
// Avoid SQL injections using bound parameters
$average = Employees::average(array(
    "column"     => "age",
    "conditions" => "area > ?0",
    "bind"       => array($area)
));

最大/最小例子：

Max/Min examples:

<?php
// What is the oldest age of all employees?
$age = Employees::maximum(array("column" => "age"));
// What is the oldest of employees from the Sales area?
$age = Employees::maximum(array(
    "column"     => "age",
    "conditions" => "area = 'Sales'"
));
// What is the lowest salary of all employees?
$salary = Employees::minimum(array("column" => "salary"));

Hydration模式Hydration Modes

正如上面提到的,结果集是一个完整的集合对象,这意味着每一个返回的结果是一个对象，它代表数据库中的一行。这些对象可以被修改并再次持久保存在数据库中:

As mentioned above, resultsets are collections of complete objects, this means that every returned result is an object representing a row in the database. These objects can be modified and saved again to persistence:

<?php
// Manipulating a resultset of complete objects
foreach (Robots::find() as $robot) {
    $robot->year = 2000;
    $robot->save();
}

有时获取的数据只需要以只读模式呈现给用户,在这种情况下变更记录的呈现方式可以解决这个问题。这种变更对象在结果集中的呈现方式的方法被叫做“Hydration模式”:

Sometimes records are obtained only to be presented to a user in read-only mode, in these cases it may be useful to change the way in which records are represented to facilitate their handling. The strategy used to represent objects returned in a resultset is called ‘hydration mode’:

<?php
use Phalcon\Mvc\Model\Resultset;
$robots = Robots::find();
//Return every robot as an array
$robots->setHydrateMode(Resultset::HYDRATE_ARRAYS);
foreach ($robots as $robot) {
    echo $robot['year'], PHP_EOL;
}
//Return every robot as an stdClass
$robots->setHydrateMode(Resultset::HYDRATE_OBJECTS);
foreach ($robots as $robot) {
    echo $robot->year, PHP_EOL;
}
//Return every robot as a Robots instance
$robots->setHydrateMode(Resultset::HYDRATE_RECORDS);
foreach ($robots as $robot) {
    echo $robot->year, PHP_EOL;
}

Hydration模式也可以被作为参数传递给“find”:

Hydration mode can also be passed as a parameter of ‘find’:

<?php
use Phalcon\Mvc\Model\Resultset;
$robots = Robots::find(array(
    'hydration' => Resultset::HYDRATE_ARRAYS
));
foreach ($robots as $robot) {
    echo $robot['year'], PHP_EOL;
}

创建与更新记录Creating Updating/Records

Phalcon\Mvc\Model::save()方法允许您创建/更新记录根据表中是否已经存在相关的记录。内部调用save实现创建和更新:doc:Phalcon\Mvc\Model <../api/Phalcon_Mvc_Model>。为实现这个功能必须正确地为表定义一个主键来确定一个记录应该被更新还是创建。

The method Phalcon\Mvc\Model::save() allows you to create/update records according to whether they already exist in the table associated with a model. The save method is called internally by the create and update methods of Phalcon\Mvc\Model. For this to work as expected it is necessary to have properly defined a primary key in the entity to determine whether a record should be updated or created.

如果虚拟外键和事件在模型中定义，save也验证器相关联的方法:

Also the method executes associated validators, virtual foreign keys and events that are defined in the model:

<?php
$robot       = new Robots();
$robot->type = "mechanical";
$robot->name = "Astro Boy";
$robot->year = 1952;
if ($robot->save() == false) {
    echo "Umh, We can't store robots right now: \n";
    foreach ($robot->getMessages() as $message) {
        echo $message, "\n";
    }
} else {
    echo "Great, a new robot was saved successfully!";
}

数组可以直接被传递给save方法，从而避免为每一列单独赋值。 Phalcon\Mvc\Model将检查是否有实现setter列，如果有则优先考虑setter,而不使用指定数组的值:

An array could be passed to “save” to avoid assign every column manually. Phalcon\Mvc\Model will check if there are setters implemented for the columns passed in the array giving priority to them instead of assign directly the values of the attributes:

<?php
$robot = new Robots();
$robot->save(array(
    "type" => "mechanical",
    "name" => "Astro Boy",
    "year" => 1952
));

数组传递的值会根据属性类型自动转义。所以你可以传递一个非法的数组,而不用担心可能的SQL注入:

Values assigned directly or via the array of attributes are escaped/sanitized according to the related attribute data type. So you can pass an insecure array without worrying about possible SQL injections:

<?php
$robot = new Robots();
$robot->save($_POST);

没有预防措施，攻击者可能会设置数据库中任何列的值。如果你想允许用户插入/更新模型的每一列中,即使这些字段不在提交表单中，可以使用这种方式。

Without precautions mass assignment could allow attackers to set any database column’s value. Only use this feature if you want to permit a user to insert/update every column in the model, even if those fields are not in the submitted form.

当有大量参数赋值的时候，可以为save设置一个白名单参数，只有在参数中的值才会被保存:

You can set an additional parameter in ‘save’ to set a whitelist of fields that only must taken into account when doing the mass assignment:

<?php
$robot = new Robots();
$robot->save($_POST, array('name', 'type'));

创建与更新结果判断Create/Update with Confidence

如果应用有许多操作，我们希望去创建一条记录而程序实际上却执行了更新，这种情况可能会在使用Phalcon\Mvc\Model::save()保存记录的时候产生。如果想彻底避免这种情况发生，可以使用create() 或者 update()替代save()方法：

When an application has a lot of competition, we could be expecting create a record but it is actually updated. This could happen if we use Phalcon\Mvc\Model::save() to persist the records in the database. If we want to be absolutely sure that a record is created or updated, we can change the save() call with create() or update():

<?php
$robot       = new Robots();
$robot->type = "mechanical";
$robot->name = "Astro Boy";
$robot->year = 1952;
//This record only must be created
if ($robot->create() == false) {
    echo "Umh, We can't store robots right now: \n";
    foreach ($robot->getMessages() as $message) {
        echo $message, "\n";
    }
} else {
    echo "Great, a new robot was created successfully!";
}

create和update方法也接受数组作为参数。

These methods “create” and “update” also accept an array of values as parameter.

自动生成标识列Auto-generated identity columns

有些模型有标示列。这些列通常是映射表的主键。Phalcon\Mvc\Model 在产生SQL INSERT的时候可以自动忽略这些列,数据库系统会自动为其生成一个值。在每次新的记录被创建后，这些标示列会被数据库自动产生的值赋值:

Some models may have identity columns. These columns usually are the primary key of the mapped table. Phalcon\Mvc\Model can recognize the identity column omitting it in the generated SQL INSERT, so the database system can generate an auto-generated value for it. Always after creating a record, the identity field will be registered with the value generated in the database system for it:

<?php
$robot->save();
echo "The generated id is: ", $robot->id;

Phalcon\Mvc\Model 能够识别标识列。根据使用的数据库不同，这些列可能是序列列（PostgreSQL）或者是auto_increment列（MySQL）。

Phalcon\Mvc\Model is able to recognize the identity column. Depending on the database system, those columns may be serial columns like in PostgreSQL or auto_increment columns in the case of MySQL.

PostgreSQL使用序列生成auto-numeric值,默认情况下,Phalcon试图获得从“table_field_seq”序列生成的价值, 例如:robots_id_seq,如果序列具有不同的名称,“getSequenceName”方法需要实现:

PostgreSQL uses sequences to generate auto-numeric values, by default, Phalcon tries to obtain the generated value from the sequence “table_field_seq”, for example: robots_id_seq, if that sequence has a different name, the method “getSequenceName” needs to be implemented:

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    public function getSequenceName()
    {
        return "robots_sequence_name";
    }
}

存储相关记录Storing related records

魔法属性可以用来存储记录及其相关属性:

Magic properties can be used to store a records and its related properties:

<?php
// Create an artist
$artist          = new Artists();
$artist->name    = 'Shinichi Osawa';
$artist->country = 'Japan';
// Create an album
$album          = new Albums();
$album->name    = 'The One';
$album->artist  = $artist; //Assign the artist
$album->year    = 2008;
//Save both records
$album->save();

保存记录及其相关has-many记录:

Saving a record and its related records in a has-many relation:

<?php
// Get an existing artist
$artist = Artists::findFirst('name = "Shinichi Osawa"');
// Create an album
$album          = new Albums();
$album->name    = 'The One';
$album->artist  = $artist;
$songs = array();
// Create a first song
$songs[0]           = new Songs();
$songs[0]->name     = 'Star Guitar';
$songs[0]->duration = '5:54';
// Create a second song
$songs[1]           = new Songs();
$songs[1]->name     = 'Last Days';
$songs[1]->duration = '4:29';
// Assign the songs array
$album->songs = $songs;
// Save the album + its songs
$album->save();

同时保存album和artist会触发事务操作处理，如果保存相关记录出错，主记录信息也不会被报错。有关任何错误信息都会返回给用户。

Saving the album and the artist at the same time implicitly makes use of a transaction so if anything goes wrong with saving the related records, the parent will not be saved either. Messages are passed back to the user for information regarding any errors.

注意:添加相关实体通过重载下面的方法是不可能的（重载下面的方法执行添加相关记录不会成功）:

Note: Adding related entities by overloading the following methods is not possible:

• PhalconMvcModel::beforeSave()
• PhalconMvcModel::beforeCreate()
• PhalconMvcModel::beforeUpdate()

需要重载PhalconMvcModel::save() 才能保存相关记录。

You need to overload PhalconMvcModel::save() for this to work from within a model.

验证信息Validation Messages

Phalcon\Mvc\Model 有个消息子系统，可以灵活的显示或者储存在执行insert/update流程中的验证信息。

Phalcon\Mvc\Model has a messaging subsystem that provides a flexible way to output or store the validation messages generated during the insert/update processes.

每个消息包含一个 Phalcon\Mvc\Model\Message 类的实例。产生的消息可以通过getMessages()获得。每个消息提供了扩展字段名，消息内容，消息类型:

Each message consists of an instance of the class Phalcon\Mvc\Model\Message. The set of messages generated can be retrieved with the method getMessages(). Each message provides extended information like the field name that generated the message or the message type:

<?php
if ($robot->save() == false) {
    foreach ($robot->getMessages() as $message) {
        echo "Message: ", $message->getMessage();
        echo "Field: ", $message->getField();
        echo "Type: ", $message->getType();
    }
}

Phalcon\Mvc\Model 会产生以下的验证信息：

Phalcon\Mvc\Model can generate the following types of validation messages:

可以在模型中getMessages()中替换或者翻译ORM生成的默认信息。

The method getMessages() can be overridden in a model to replace/translate the default messages generated automatically by the ORM:

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    public function getMessages()
    {
        $messages = array();
        foreach (parent::getMessages() as $message) {
            switch ($message->getType()) {
                case 'InvalidCreateAttempt':
                    $messages[] = 'The record cannot be created because it already exists';
                    break;
                case 'InvalidUpdateAttempt':
                    $messages[] = 'The record cannot be updated because it already exists';
                    break;
                case 'PresenceOf':
                    $messages[] = 'The field ' . $message->getField() . ' is mandatory';
                    break;
            }
        }
        return $messages;
    }
}

事件和事件管理器Events and Events Manager

数据模型允许在执行insert/update/delete触发事件。帮助我们更好的建立业务逻辑。下面是 Phalcon\Mvc\Model 支持的事件和执行顺序：

Models allow you to implement events that will be thrown when performing an insert/update/delete. They help define business rules for a certain model. The following are the events supported by Phalcon\Mvc\Model and their order of execution:

模型中自定义事件Implementing Events in the Model’s class

让一个模型对事件做出反应更简单的方法是在事件模型的类中实现一个具有相同名称的方法:

The easier way to make a model react to events is implement a method with the same name of the event in the model’s class:

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    public function beforeValidationOnCreate()
    {
        echo "This is executed before creating a Robot!";
    }
}

事件在执行之前进行赋值非常有用,例如:

Events can be useful to assign values before performing an operation, for example:

<?php
use Phalcon\Mvc\Model;
class Products extends Model
{
    public function beforeCreate()
    {
        //Set the creation date
        $this->created_at = date('Y-m-d H:i:s');
    }
    public function beforeUpdate()
    {
        //Set the modification date
        $this->modified_in = date('Y-m-d H:i:s');
    }
}

使用自定义事件管理器Using a custom Events Manager

事件管理器组件被整合到 Phalcon\Events\Manager ，我们可以创建事件监听器，并监听事件是否被触发。

Additionally, this component is integrated with Phalcon\Events\Manager, this means we can create listeners that run when an event is triggered.

<?php
use Phalcon\Mvc\Model;
use Phalcon\Events\Manager as EventsManager;
class Robots extends Model
{
    public function initialize()
    {
        $eventsManager = new EventsManager();
        //Attach an anonymous function as a listener for "model" events
        $eventsManager->attach('model', function($event, $robot) {
            if ($event->getType() == 'beforeSave') {
                if ($robot->name == 'Scooby Doo') {
                    echo "Scooby Doo isn't a robot!";
                    return false;
                }
            }
            return true;
        });
        //Attach the events manager to the event
        $this->setEventsManager($eventsManager);
    }
}

在上面的例子中,事件管理器只是充当在一个对象和一个侦听器之间的桥梁(匿名函数)。在‘robots’保存的时候事件将被监听者收到:

In the example given above, EventsManager only acts as a bridge between an object and a listener (the anonymous function). Events will be fired to the listener when ‘robots’ are saved:

<?php
$robot       = new Robots();
$robot->name = 'Scooby Doo';
$robot->year = 1969;
$robot->save();

如果我们想要在我们的应用程序中使用相同的事件管理器,我们需要将它分配给模型管理器：

If we want all objects created in our application use the same EventsManager, then we need to assign it to the Models Manager:

<?php
//Registering the modelsManager service
$di->setShared('modelsManager', function() {
    $eventsManager = new \Phalcon\Events\Manager();
    //Attach an anonymous function as a listener for "model" events
    $eventsManager->attach('model', function($event, $model){
        //Catch events produced by the Robots model
        if (get_class($model) == 'Robots') {
            if ($event->getType() == 'beforeSave') {
                if ($model->name == 'Scooby Doo') {
                    echo "Scooby Doo isn't a robot!";
                    return false;
                }
            }
        }
        return true;
    });
    //Setting a default EventsManager
    $modelsManager = new ModelsManager();
    $modelsManager->setEventsManager($eventsManager);
    return $modelsManager;
});

如果一个侦听器返回false,将停止当前正在执行的操作。

If a listener returns false that will stop the operation that is executing currently.

实现业务逻辑Implementing a Business Rule

当执行插入、更新或删除时,该模型验证在表中是否有任何和事件相关的方法。

When an insert, update or delete is executed, the model verifies if there are any methods with the names of the events listed in the table above.

我们建议验证方法声明为protected,防止业务逻辑实现被公开曝光。

We recommend that validation methods are declared protected to prevent that business logic implementation from being exposed publicly.

下面的示例实现一个事件来验证年份小于0的不能被更新或插入:

The following example implements an event that validates the year cannot be smaller than 0 on update or insert:

<?php
use Phalcon\Mvc\Model;
class Robots extends Model
{
    public function beforeSave()
    {
        if ($this->year < 0) {
            echo "Year cannot be smaller than zero!";
            return false;
        }
    }
}

一些事件返回false作为停止当前操作的指示。如果一个事件不返回任何值,:doc:`Phalcon\Mvc\Model <../api/Phalcon_Mvc_Model>`假设返回了true。

Some events return false as an indication to stop the current operation. If an event doesn’t return anything, Phalcon\Mvc\Model will assume a true value.

验证数据完整性Validating Data Integrity

Phalcon\Mvc\Model 提供了一些事件来验证数据和实施业务规则。特殊的”验证”事件允许我们调用内置的验证器验证记录。Phalcon暴露一些内置的验证器,我们可以使用这些验证。

Phalcon\Mvc\Model provides several events to validate data and implement business rules. The special “validation” event allows us to call built-in validators over the record. Phalcon exposes a few built-in validators that can be used at this stage of validation.

The following example shows how to use it:

<?php
use Phalcon\Mvc\Model;
use Phalcon\Mvc\Model\Validator\Uniqueness;
use Phalcon\Mvc\Model\Validator\InclusionIn;
class Robots extends Model
{
    public function validation()
    {
        $this->validate(new InclusionIn(
            array(
                "field"  => "type",
                "domain" => array("Mechanical", "Virtual")
            )
        ));
        $this->validate(new Uniqueness(
            array(
                "field"   => "name",
                "message" => "The robot name must be unique"
            )
        ));
        return $this->validationHasFailed() != true;
    }
}

上面的例子演示了使用内置“InclusionIn”(包含)验证器。它验证了字段“type”是否在domain列表中。如果验证失败就会返回false。内置的验证器如下所示：

The above example performs a validation using the built-in validator “InclusionIn”. It checks the value of the field “type” in a domain list. If the value is not included in the method then the validator will fail and return false. The following built-in validators are available:

除了内置的验证器，我们还可以自定义验证器：

In addition to the built-in validators, you can create your own validators:

<?php
use Phalcon\Mvc\Model\Validator;
use Phalcon\Mvc\Model\ValidatorInterface;
class MaxMinValidator extends Validator implements ValidatorInterface
{
    public function validate($model)
    {
        $field  = $this->getOption('field');
        $min    = $this->getOption('min');
        $max    = $this->getOption('max');
        $value  = $model->$field;
        if ($min <= $value && $value <= $max) {
            $this->appendMessage(
                "The field doesn't have the right range of values",
                $field,
                "MaxMinValidator"
            );
            return false;
        }
        return true;
    }
}

将验证器加入模型：

Adding the validator to a model:

<?php
use Phalcon\Mvc\Model;
class Customers extends Model
{
    public function validation()
    {
        $this->validate(new MaxMinValidator(
            array(
                "field" => "price",
                "min"   => 10,
                "max"   => 100
            )
        ));
        if ($this->validationHasFailed() == true) {
            return false;
        }
    }
}

创建验证器的想法是让他们可以在几个模型之间可重用。一个验证器也可以一样简单定义如下:

The idea of creating validators is make them reusable between several models. A validator can also be as simple as:

<?php
use Phalcon\Mvc\Model;
use Phalcon\Mvc\Model\Message;
class Robots extends Model
{
    public function validation()
    {
        if ($this->type == "Old") {
            $message = new Message(
                "Sorry, old robots are not allowed anymore",
                "type",
                "MyType"
            );
            $this->appendMessage($message);
            return false;
        }
        return true;
    }
}

避免SQL注入Avoiding SQL injections

每个值分配给模型属性会根据数据类型被转义。程序员不必手动转义每个值保存到数据库。Phalcon使用内置的 bound parameters 由PDO提供的功能自动转义存入数据库的值。

Every value assigned to a model attribute is escaped depending of its data type. A developer doesn’t need to escape manually each value before storing it on the database. Phalcon uses internally the bound parameters capability provided by PDO to automatically escape every value to be stored in the database.

mysql> desc products;
+------------------+------------------+------+-----+---------+----------------+
| Field            | Type             | Null | Key | Default | Extra          |
+------------------+------------------+------+-----+---------+----------------+
| id               | int(10) unsigned | NO   | PRI | NULL    | auto_increment |
| product_types_id | int(10) unsigned | NO   | MUL | NULL    |                |
| name             | varchar(70)      | NO   |     | NULL    |                |
| price            | decimal(16,2)    | NO   |     | NULL    |                |
| active           | char(1)          | YES  |     | NULL    |                |
+------------------+------------------+------+-----+---------+----------------+
5 rows in set (0.00 sec)

如果我们以一个安全的方式使用PDO存储记录,我们需要编写下面的代码:

If we use just PDO to store a record in a secure way, we need to write the following code:

<?php
$name           = 'Artichoke';
$price          = 10.5;
$active         = 'Y';
$productTypesId = 1;
$sql = 'INSERT INTO products VALUES (null, :productTypesId, :name, :price, :active)';
$sth = $dbh->prepare($sql);
$sth->bindParam(':productTypesId', $productTypesId, PDO::PARAM_INT);
$sth->bindParam(':name', $name, PDO::PARAM_STR, 70);
$sth->bindParam(':price', doubleval($price));
$sth->bindParam(':active', $active, PDO::PARAM_STR, 1);
$sth->execute();