写在前面

本文为学习Propel框架使用的笔记，默认已经安装好Propel环境，若有读者不知如何安装Propel，可参考《听说你PHP配置Composer遇到了一些困境》一文。

Propel初始化

执行propel init指令，进行Propel初始化，若读者执行该指令遇到问题可以参考《【PHP】使用Propel踩过的坑》一文。执行完propel init，需设置数据库类型、IP地址、端口号、数据库名、用户名、密码、编码方式，然后设置相应配置文件的存放位置和命名空间，如下图所示：

CRUD（增删改查）操作

• Creating Rows
  以名为author的表为例，进行插入操作，语句如下：

<?php
$author = new Author();
$author->setFirstName('Jane');
$author->setLastName('Austen');
$author->save();

上述语句等效于：

INSERT INTO author (first_name, last_name) VALUES ('Jane', 'Austen');

通过setXXX()方法插入对应的列，括号中的参数表示插入的值；通过save()方法执行插入语句，这里表和列名都用小写字母+下划线的命名方式。

• Reading Object Properties
  Propel支持读取某一条记录的相关信息，并将其语句如下：

<?php
echo $author->getId();        // 1
echo $author->getFirstName(); // 'Jane'
echo $author->getLastName();  // 'Austen'

如果原来数据库表未定义id，则Propel会默认定义一个整型自增的id；通过getXXX()方法得到相应属性（列）的值。除了将属性一个一个显示出来，还提供了便捷的方法将对象以json、yaml、数组、XML、CVS和纯字符串的格式显示出来：

<?php
echo $author->toJSON();
echo $author->toArray();
echo $author->toXML();
echo $author->toYAML();
echo $author->toJSON();
echo $author->toCSV();
echo $author->__toString();

如果想把json数据转为一个对象，可以调用fromJSON()，对应的还有fromArray()、fromXML()、fromYAML()、fromCSV()。

• Retrieving Rows
  除了读取对象外，Propel还支持条件查询来读取记录。
  • Retrieving by Primary Key
    最简单的使用就是通过主键来读取记录，代码如下：

<?php
$q = new AuthorQuery();
$firstAuthor = $q->findPK(1);

上述代码中AuthorQuery类是在命名空间文件夹里自动生成的。如笔者的命名空间为kq，所以在这个文件夹下会在执行propel init指令时自动生成各种XXXQuery类，如下图所示：

use kq\kq; // use 文件夹\文件夹...；

而变量firstAuthor，如果有找到记录，则它是一个Author对象，如果没有找到，则它为NULL。上述代码实现的效果相当于：

SELECT author.id, author.first_name, author.last_name
FROM `author`
WHERE author.id = 1
LIMIT 1;

和Java语言类似，Propel也提供了工厂模式，上述语句也可以写成工厂模式的形式：

<?php
$firstAuthor = AuthorQuery::create()->findPK(1);

如果想要通过主键查找多条记录，则可以调用findPKs()方法，如下：

<?php
$selectedAuthors = AuthorQuery::create()->findPKs(array(1,2,3,4,5,6,7));

这时候selectedAuthors就是一个Author对象的集合。

• Querying the Database
  除了findPK()方法，读者们还可以通过find()方法来查询记录，如下：

<?php
$authors = AuthorQuery::create()->find();

上述查询得到的结果是author表的所有记录，如果想要通过类似于WHERE的Sql语法筛选记录，可以用filterByXXX()方法实现，其代码实现如下：

<?php
$authors = AuthorQuery::create()
      ->filterByFirstName('Jane')
      ->find();

上述代码得到的authors对象可用foreach来遍历：

foreach($authors as $author) {
        echo $author->getFirstName();
}

Sql语句中有ORDER BY和LIMIT语法，在Propel中可通过orderByXXX()方法和limit()方法实现：

<?php
$authors = AuthorQuery::create()
      ->orderByLastName()
      ->limit(10)
      ->find();

如果想实现limit(1)的效果，可直接调用findOne()：

<?php
$author = AuthorQuery::create()
      ->filterByFirstName('Jane')
      ->findOne();

上述语句可简写为一行：

<?php
$author = AuthorQuery::create()->findOneByFirstName('Jane');

• Using Custom SQL
  Propel作为orm框架，其提供的方法在给我们带来便利的同时也带来了局限。为了避免这种限制，Propel提供了自定义Sql语句的执行方法：

<?php
use Propel\Runtime\Propel;
$con = Propel::getWriteConnection(\Map\BookTableMap::DATABASE_NAME);
$sql = "SELECT * FROM book WHERE id NOT IN "
        ."(SELECT book_review.book_id FROM book_review"
        ." INNER JOIN author ON (book_review.author_id=author.ID)"
        ." WHERE author.last_name = :name)";
$stmt = $con->prepare($sql);
$stmt->execute(array(':name' => 'Austen'));
// 上述代码执行的是查找作者姓氏不为`Austen`的书籍。

自定义Sql语句执行得到的是一个结果集（resultset），如果想把结果集转为对象，可以调用ObjectFormatter类的format方法：

<?php
use Propel\Runtime\Formatter\ObjectFormatter;
$con = Propel::getWriteConnection(\Map\BookTableMap::DATABASE_NAME);
$formatter = new ObjectFormatter();
$formatter->setClass('\Book'); 
$books = $formatter->format($con->getDataFetcher($stmt));

划重点：使用自定义的Sql语句需要注意以下三点：
* 结果集列必须是数字索引（The resultset columns must be numerically indexed）
* 结果集必须包含数据表的所有列，延迟加载的列除外（The resultset must contain all the columns of the table (except lazy-load columns)）
* 结果集必须按照scheme.xml文件指定的顺序以相同排序方式排序（The resultset must have columns in the same order as they are defined in the schema.xml file）

PS: 对于上述第一点，笔者不理解其表达的意思，望过来人指点一二。

• Updating Objects
  修改数据库基于读取数据库，通过读取获取对象，再通过setXXX()和save()方法对对象属性进行修改并存入数据库：

<?php
$author = AuthorQuery::create()->findOneByFirstName('Jane');
$author->setLastName('Austen');
$author->save();

除上述方法外，Propel提供了update()方法，直接对数据进行修改：

<?php
AuthorQuery::create()
      ->filterByFirstName('Jane')
      ->update(array('LastName' => 'Austen'));

官方推荐使用update()方法对数据做修改

• Deleting Objects
  删除数据记录与修改数据类似，也是通过读取获取对象，再调用delete()方法对数据进行删除：

<?php
$author = AuthorQuery::create()->findOneByFirstName('Jane');
$author->delete();

同样，上述代码还可以优雅地写为：

<?php
AuthorQuery::create()
      ->filterByFirstName('Jane')
      ->delete();

敲黑板！！！这里注意一点，被删除的对象（如上面代码中的author对象），依然可以通过getXXX()方法获取被删除的记录的属性值：

<?php
echo $author->isDeleted();    // true
echo $author->getFirstName(); // 'Jane'

• Query Termination Methods
  像上述提到的find()、update()、delete()这样不返回当前对象的方法称之为“终止方法（Termination Methods）”（官网原文：The Query methods that don’t return the current query object are called “Termination Methods”）。除了上述提到的终止方法外，还有两个方法：http://propelorm.org/documentation/03-basic-crud.html
  • count()
    该方法返回查询结果的记录条数:

<?php
$nbAuthors = AuthorQuery::create()->count();

• paginate()
  通过调用该方法，传入当前页和每页记录条数可实现实现分页的效果：

<?php
$authorPager = AuthorQuery::create()->paginate($page = 1, $maxPerPage = 10);
foreach ($authorPager as $author) {
      echo $author->getFirstName();
}

pager对象可以有以下方法可以调用：

<?php
// total number of results if not paginated
echo $pager->getNbResults();
// 如果maxPerPage小于总的条数，则返回true；否则反之
echo $pager->haveToPaginate(); 
// 返回第一页记录
echo $pager->getFirstIndex(); 
// 返回最后一页记录
echo $pager->getLastIndex();
 // array of page numbers around the current page; useful to display pagination controls
$links = $pager->getLinks(5); 
# 对于第一个方法和最后一个方法，笔者担心自己误人子弟，读者们可以根据英文注解，实际动手写一下代码验证一下

• Collections And On-Demand Hydration
  Propel对数据查询进行了优化，当查询数据量比较大时，Propel提供了“按需分配”的机制，这样防止了内存溢出的现象，其代码实现上只需要加入一句代码即可：

<?php
$authors = AuthorQuery::create()
  ->limit(50000)
  ->setFormatter(ModelCriteria::FORMAT_ON_DEMAND) // just add this line
  ->find();
foreach ($authors as $author) {
      echo $author->getFirstName();
}

ModelCriteria::FORMAT_ON_DEMAND用在与对象相关的查询中，如果将查询到的数据存在数组中，可以使用ModelCriteria::FORMAT_ARRAY。

• Propel Instance Pool
  为了防止在同一个PHP脚本文件中用到多个相同的数据查询，Propel提供了“实例池(Instance Pool)”的概念，如下面代码，执行完一条查询一句后，再此执行，则第二次直接调用第一次的实例：

<?php
// first call
$author1 = AuthorQuery::create()->findPk(1);
// Issues a SELECT query
...
// second call
$author2 = AuthorQuery::create()->findPk(1);
// Skips the SQL query and returns the existing $author1 object

参考链接

http://propelorm.org/documentation/03-basic-crud.html

笔者正在学习中，文章稍后更新...