PEAR的MDB2学习笔记

■ 安装

需要安装两个包，一是MDB2本身基础类：[url=http://pear.php.net/package /MDB2]MDB2包[/url]，二是相应数据库的驱动包[url=http://pear.php.net/package /MDB2_Driver_mysql]MDB2_Driver_mssql[/url]。如果需要，还需配上[url=http: //pear.php.net/package/PEAR]PEAR基础包[/url]。

■ DSN —— The Data Source Name

DNS由以下几部分构成：
* phptype  ：使用的数据库取得类型 比如 mysql，mysqli，pgsql
* dbsyntax ： Database used with regards to SQL syntax etc.
* protocol  ： Communication protocol to use ( i.e. tcp, unix etc.)使用的协议
* hostspec ： 服务器地址 (hostname[:port])
* database ：数据名称
* username ：用户名 
* password ：密码
* proto_opts: Maybe used with protocol 
* option ： 额外的选项，不同的option之间用&分割，可以设置的选项有：charset——设置字符集、new_link——有的数据库默认不允许同时打开多个连接，用这个选项可以强行开启一个新连接。例子： ?charset=utf8

不同的写法：
phptype://username:password@protocol+hostspec:110//usr/db_file.db
phptype://username:password@hostspec/database
phptype://username:password@hostspec
phptype://username@hostspec
phptype://hostspec/database
phptype://hostspec
phptype:///database
phptype:///database?option=value&anotheroption=anothervalue
phptype(dbsyntax)
phptype

如果以上的各种属性中，存在dsn书写规则中用到的特殊字符的话，用下面的方法转义：: = %3a   / = %2f   @ = %40
+ = %2b   ( = %28   ) = %29
? = %3f   = = %3d   & = %26

例子：

Connect to database through a socket 从socket接口连接数据库：
mysql://user@unix(/path/to/socket)/pear

Connect to database on a non standard port 从非默认端口连接
pgsql://user:pass@tcp(localhost:5555)/pear



■ 连接数据库
连接数据库有三种方式：

factory() ：并不会立即连接数据库，在遇到对数据库发送命令时，才会执行连接。
connect() ：立即连接数据库
singleton() ：用factory()的方式，为单件模式

这三个方法都会返回一个MDB2_Driver_Common 的实例，它们的第一个参数要么是DSN字符串，要么也可以是所有参数的数组，格式如下：

$dsn = array(
    'phptype'  => false,
    'dbsyntax' => false,
    'username' => false,
    'password' => false,
    'protocol' => false,
    'hostspec' => false,
    'port'     => false,
    'socket'   => false,
    'database' => false,
    'new_link' => false,
    'service'  => false, // only in oci8
);

第二个参数是可选的，可以提供数据库运行时设置信息。

可以使用PEAR::isError()或者MDB2_Driver_Common 的方法isError()来检测有无错误发生。

可选参数

setOption()和getOption()方法可以设置一些额外的数据库操作参数。参数有：

# MDB2_PORTABILITY_ALL 
开启所有的移植性属性
# MDB2_PORTABILITY_DELETE_COUNT
强制delete操作返回其所影响的行数，有些数据库是不会返回这个信息的，这时可以使用这个参数。
# MDB2_PORTABILITY_EMPTY_TO_NULL
将empty的值等价于null，在oracle中是这样处理empty值的，而其他大多数数据库并不是。
# MDB2_PORTABILITY_ERRORS
Makes certain error messages in certain drivers compatible with those from other DBMSs
# MDB2_PORTABILITY_FIX_ASSOC_FIELD_NAMES
This removes any qualifiers from keys in associative fetches. Some RDBMS, for example SQLite, will default to use the fully qualified name for a column in assoc fetches if it is qualified in a query.
#MDB2_PORTABILITY_FIX_CASE
用户指定数据结果的关联数组是统一使用固定的大小写键，它不会影响到query中的内容，而只影响到返回的数据
# MDB2_PORTABILITY_NONE
关闭所有的移植特性
# MDB2_PORTABILITY_NUMROWS
numRows()这个方法在oracle下也可用
# MDB2_PORTABILITY_RTRIM
Right trim the data output for all data fetches. This does not apply to drivers for RDBMS that automatically right trim values of fixed length character values, even if they do not right trim value of variable length character values.


■ 数据库查询

query() 方法，执行会返回数据结果的查询，比如select，返回的结果是MDB2_Result 的实例，发生错误时，返回MDB2_Error的实例。它不适合用来执行数据操作的请求，比如insert。

exec() 方法，用于执行数据操作的情况下，可能有两种返回结果，或者是此次操作所影响到的数据行数，或者一个MDB2_Error 的实例。

setLimit() 方法，用于设置select，delete等操作的数据读取范围
setLimit($offset,$start) 方法来设置limit功能，第一个参数是偏移量，第二个参数是开始的序号，这个序号是从0开始计数的。

■ sql中数据的过滤

quote() 方法，用来依照各个数据库的特性，对sql进行过滤转义，它有四个参数，只有第一个参数是必须的。四个参数分别是：要过滤的值、数据的类型（datatype）、是否要quote值，是否要解析通配符。

第二个参数，数据类型（datatype）分为：
Text
Boolean
Integer
Decimal 十进制数？
Float
Date
Time 一天的时间？类似HH:MI:SS ？
Time stamp 类似 YYYY-MM-DD HH:MI:SS
Large object (file)

第三个参数，With the third parameter of the quote() you can specify whether or not the above fields should be individually quoted

<?php
$query = 'INSERT INTO sometable (textfield1, boolfield2, datefield3) VALUES ('
    .$mdb2->quote($val1, "text", true).', '
    .$mdb2->quote($val2, "boolean", false).', '
    .$mdb2->quote($val3, "date", true).')';
?>
The above example will quote the fields and the resulting SQL will look as such: INSERT INTO sometable FIELDS (textfield1, boolfield2, datefield3) VALUES ('blah', 1, '2006-02-21')
where the values defined were the values inserted accordingly. You will notice that the "boolfield2" is unquoted as we specified FALSE in the quote() method.

quoteIdentifier() 方法，为数据库的特殊字段quote，比如表名，字段名等。

MDB2的一些方法，可能会引起内部的数据查询，这是可以使用MDB2的quote_identifier 参数来指定MDB2的内部查询中，对数据库相关字段进行quote。不过，这个参数与用户提交的sql是否进行quote_identifier无关。

$mdb2->setOption('quote_identifier', true);

Escape
If you want to escape a value, without surrounding it with quotes, you can use the escape() method. If you also want to escape the wildcards (_ and %), set the second parameter to TRUE

If you just want to escape the wildcards in a value, you can use the escapePattern() method.

escape的作用和quote类似，不过quote出的值，会自动加上单引号，包含起来；escape则不会。同时，escape还可以指定第二个参数，来过滤到字符串中出现的通配符。

如果只是希望过滤值中的通配符，而不希望转义其中的特殊字符，比如单引号，则可以直接使用方法escapePattern()

■ 获取数据

有四个方法，两种不同的方式来获取数据
1.fetchRow和fetchoOne 只从资源中获取一行或者一个字段的数据，指针自动前移
2.fetchAll和fetchCol 取得资源的所有的数据，返回全部的内容，或者只返回其中的一列

可以在获取数据时，指定获取数据的格式，参数为
MDB2_FETCHMODE_ORDERED  默认返回数字序列数组
MDB2_FETCHMODE_ASSOC    返回关联数组
MDB2_FETCHMODE_OBJECT  返回一个对象

用法 $res->fetchRow(MDB2_FETCHMODE_ASSOC)

用setFetchMode() 方法指定默认的数据获取方式

fetchRow($mode,$rownum)，可以有两个参数，第一个参数是fetchmode，设置数据获取方式，第二个参数是行数序列，指定提取资源中的第几行数据

释放资源 $res->free()

获取数据库返回的原始资源 $res->getResource()

从query results 中获取更多信息
numRows()  资源中的行数
numCols()    资源中的列数
rowCount()  资源中的指针当前位于第几行
getColumnNames()  返回列名，以及列名在表中的顺序
seek()  在资源中查找特定行是否存在，如果存在返回MDB2_OK，不存在返回 MDB2 error。只有开启了'result_buffering' 选项时才能向后搜索，否则只能向前
nextResult() 当在使用多次查找时，使用它来切换到下一个query语句获得的资源，当'multi_query'选项开启时才有效。
例子：
<?php
$multi_query = $this->db->setOption('multi_query', true);
// check if multi_query can be enabled
if (!PEAR::isError($multi_query))
{
    $res =& $mdb2->query('SELECT * FROM phptest; SELECT * FROM phptest2;');
    $data1 = $res->fetchAll();
    // move result pointer to the next result
    $res->nextResult();
    $data2 = $res->fetchAll();
}
else
{
    echo 'multi_query option is not supported';
}

?>

bindColumn($var,$col,$type)， 将一个用户变量与表的字段绑定，这样从资源中获取的每一行数据时，用户变量会被自动赋予相应字段的值。

一次性执行查询和提取数据

queryOne()
queryRow()
queryCol()
queryAll()

对于使用预处理方式的用户，可以在载入“Extended”模块后，使用一下方法:
getOne(),
getRow(),
getCol(),
getAll()
getAssoc().

<?php
$mdb2->loadModule('Extended');
$query = 'SELECT * FROM phptest WHERE id = ?';
$data = $mdb2->extended->getRow($query, null, array(1), array('integer'));
print_r($data);
?>

■ 预处理

$db->prepare('INSERT INTO numbers (number) VALUES (?)', array('integer'), MDB2_PREPARE_MANIP)

第二个参数用于指定通配符字段的数据类型
第三个参数
     如果是insert，update，delete这样的数据操作，它应该设为 MDB2_PREPARE_MANIP，以返回操作行数或者行标
     如果是select提取数据的操作，应该设为MDB2_PREPARE_RESULT ，以获取数据结果

如果使用“?”做通配符
<?php
// Once you have a valid MDB2 object named $mdb2...
$types = array('integer', 'text', 'text');
$sth = $mdb2->prepare('INSERT INTO numbers VALUES (?, ?, ?)', $types, MDB2_PREPARE_MANIP);

$data = array(1, 'one', 'en');   //数据为一般数组
$affectedRows = $sth->execute($data);
?>

如果使用 :abc 的通配符
<?php
// Once you have a valid MDB2 object named $mdb2...
$types = array('integer', 'text', 'text');
$sth = $mdb2->prepare('INSERT INTO numbers VALUES (:id, :text, :lang)', $types);

$data = array('id' => 1, 'name' => 'one', 'lang' => 'en');  //数据为关联数组
$affectedRows = $sth->execute($data);
?>