Nio’s Weblog

今天试着用 Propel 生成了数据库操作的类文件，简单记录一下。

目录结构

生成 PHP 类文件的工作主要在 peopel-generator 目录下进行。在正确安装完成之后，peopel-generator 的目录结构应该如下：

propel-generator  
  |-- classes
  |    +-- propel
  |         |-- engine
  |         |    |-- database
  |         |    |    |-- model
  |         |    |    +-- transform
  |         |    +-- sql
  |         +-- phing    
  |-- dtd
  |-- projects
  |    +-- bookstore
  |-- templates
  +-- test
       |-- classes
       |    +-- propel
       +-- etc

classes：Propel 所用到的所有类文件；
dtd：对应于数据库描述文件（schema.xml）的 DTD 文件－－DTD 是 XML 的基础，感兴趣的可以到 W3 School 学习；
projects：此目录用于存放各个项目的文件，每个项目对应于一个子目录，Propel 自带有 bookstore 项目作为样例。Propel 会从这些项目的目录中读取 schema 和配置文件，然后将生成的文件放入输出目录 build（如：projects/bookstore/build）中；
templates：存放着用于创建 PHP 文件的模板及 SQL 文件的数据模型；
test：PHPUnit2 测试用例。

创建数据库描述文件

首先需要在 projects 目录下创建项目目录（假设项目名为“infor96”），然后在此目录下创建数据库描述文件 schema.xml，内容如下（这里只对一个数据表进行试验测试）：

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<database name="infor96" defaultIdMethod="native">
 <table name="user" description="User Table">
  <column
    name="uid"
    required="true"
    primaryKey="true"
    type="VARCHAR"
    size="16"
    description="User Id"/>
  <column
    name="pwd"
    required="true"
    type="VARCHAR"
    size="16"
    description="User's Password"/>
  <column
    name="name"
    required="true"
    type="VARCHAR"
    size="10"
    description="User's True Name"/>
 </table>
</database>

可以清楚的看到这个项目的数据库名为“infor96”，有一个表，表名为“user”，这个表有 3 个字段：uid、pwd、name，如果有多个表的话，在 <database> …. </database> 之间加入多个 <table> 即可。其他标签属性比较简单，type 是字段类型，size 是大小，primaryKey 是“主键”。

设置创建属性

在项目目录（projects/infor96/）下创建文件 build.properties，最为简单的内容是：

# 项目名
propel.project = infor96

# 数据库类型
propel.database = mysql

设置运行时属性

在项目目录下创建 runtime-conf.xml 文件，内容为：

<?xml version="1.0" encoding="ISO-8859-1"?>

<config>
 <log>
  <ident>propel-infor96</ident>
  <level>7</level>
 </log>
 <propel>
  <datasources default="infor96">
   <datasource id="infor96">
    <adapter>mysql</adapter>
    <connection>
     <phptype>mysql</phptype>
     <hostspec>localhost</hostspec>
     <database>infor96</database>
     <username>infor96</username>
     <password>infor96</password>
    </connection>
   </datasource>
  </datasources>
 </propel>
</config>

可以看出，这个文件其实就是设置运行的时候需要用到的连接数据库参数，数据库名、用户、密码等。当生成 PHP 类文件时，这个文件会被自动转换成 projects/infor96/build/conf/runtime-conf.php，此文件路径在 Propel 初始化方法 Propel :: init() 中当参数传递。

生成 PHP 类文件

一切准备就绪，开始生成 PHP 类文件的工作了：

$ cd /usr/local/propel-generator
$ cp build.properties-sample build.properties
$ phing -Dproject=infor96

自动生成工作由 phing 来完成，如果没有安装 phing 的话，可以通过运行下边命令来安装：

pear install http://phing.info/pear/phing-current.tgz

在 phing 生成 PHP 类文件的过程中，可以看到很多输出：

Buildfile: /usr/local/propel-generator/build.xml

propel-project-builder > projectcheck:

propel-project-builder > configure:
     [echo] Loading project-specific props from ./projects/infor96/build.properties

propel-project-builder > main:
    [phing] Calling Buildfile '/usr/local/propel-generator/build-propel.xml' with target 'main'

propel > main:
[phingcall] Calling Buildfile '/usr/local/propel-generator/build-propel.xml' with target 'sql'

propel > check-run-only-on-schema-change:

propel > sql-check:

propel > sql:
     [echo] +------------------------------------------+
     [echo] |                                          |
     [echo] | Generating SQL for YOUR Propel project!  |
     [echo] |                                          |
     [echo] +------------------------------------------+
[phingcall] Calling Buildfile '/usr/local/propel-generator/build-propel.xml' with target 'sql-template'

propel > sql-template:
[propel-sql] Processing: schema.xml
[propel-sql] Target database type: mysql
[propel-sql] Target package:
[propel-sql] Using template path: /usr/local/propel-generator/templates
[propel-sql] Output directory: /usr/local/propel-generator/projects/infor96/build/sql
[propel-sql] Generating SQL tables for database: infor96
[propel-sql] Writing to SQL file: /usr/local/propel-generator/projects/infor96/build/sql/schema.sql
[propel-sql]     + user
[phingcall] Calling Buildfile '/usr/local/propel-generator/build-propel.xml' with target 'om'

propel > check-run-only-on-schema-change:

propel > om-check:

propel > om:
     [echo] +------------------------------------------+
     [echo] |                                          |
     [echo] | Generating Peer-based Object Model for   |
     [echo] | YOUR Propel project!                     |
     [echo] |                                          |
     [echo] +------------------------------------------+
[phingcall] Calling Buildfile '/usr/local/propel-generator/build-propel.xml' with target 'om-template'

propel > om-template:
[propel-om] Target database type: mysql
[propel-om] Target package: infor96
[propel-om] Using template path: /usr/local/propel-generator/templates
[propel-om] Output directory: /usr/local/propel-generator/projects/infor96/build/classes
[propel-om] Processing: schema.xml
[propel-om] Processing Datamodel : schema.xml
[propel-om]   - processing database : infor96
[propel-om]     + user
[propel-om]             -> BaseUserPeer
[propel-om]             -> BaseUser
[propel-om]             -> UserMapBuilder
[phingcall] Calling Buildfile '/usr/local/propel-generator/build-propel.xml' with target 'convert-props'

propel > convert-props:
     [echo] +------------------------------------------+
     [echo] |                                          |
     [echo] | Converting project properties file to an |
     [echo] | array dump for run-time performance.     |
     [echo] |                                          |
     [echo] +------------------------------------------+
  [capsule] Using templatePath: /usr/local/propel-generator/templates
  [capsule] Generating to file /usr/local/propel-generator/projects/infor96/build/conf/infor96-conf.php
  [capsule] Parsing control template: conf/Control.tpl
BUILD FINISHED

Total time: 3.0861 seconds

生成的文件均位于 projects/infor96/build/ 目录下，PHP 类文件在 projects/infor96/build/classes/infor96/ 目录下。这些类文件中包含了很多属性和方法，可以看到，Propel 对每一个字段都提供了 get/set 方法，如：getUid() 和 setUid()。现在可以写个 PHP 调用这些类，然后通过这些类的方法去操作数据库了。这就是当初 Hibernate 的设想，像操作对象那样去操作数据库。在你写 PHP 代码中，不会出现 SQL 语句，因为这些 SQL 语句已经完全被封装在类文件中了，而这些类文件是由 Propel 自动生成的。下面是一个使用示例：

<?php
require_once 'propel/Propel.php';

// 首先需要将生成的 projects/infor96/build/ 整个项目目录移到需要用到的地方，当然可以不放到 WEB 发布目录下
// 下边传递的这个配置文件就是由运行时配置文件 runtime-conf.xml 对应生成的
Propel::init('/var/www/infor96/conf/runtime-conf.php');

include_once 'infor96/User.php';

//=======================================================
//	INSERT 示例
//=======================================================
$user = new User();
$user->setUid("Nio");
$user->setPwd("test");
$user->setName("Krazy Nio");
//	将设置的数据信息保存到数据库中，实际后台是执行了 INSERT 操作
$user->save();

//=======================================================
//	SELECT 示例
//=======================================================
$c = new Criteria();
$c->add(UserPeer::UID, "io%", Criteria::LIKE);
$c->setLimit(10); // 设置选择的记录数，相当于 MySQL 中的 LIMIT
$users = UserPeer::doSelect($c);
if ($users) {
	echo '<p>找到了如何条件的用户！</p>';
	foreach($users as $user)
		echo '<br/>帐号：' . $user->getUid() . "，姓名：" . $user->getName();
}	//end if
?>

嗯，今天的实践总结就写到这里吧，至少已经明白了原理及实现过程。