PHP中ADODB類詳解

雖然 PHP 是建構 Web 系統強有力的工具，但是 PHP 存取資料庫的功能，一直未能標準化，每一種資料庫，都使用另一種不同且不相容的應用程式介面(API)。為了填補這個缺憾，因此才有 ADODB 的出現。一旦存取資料庫的介面予以標準化，就能隱藏各種資料庫的差異，若欲轉換至其它不同的資料庫，將變得十分容易。

目前 ADODB 支援的資料庫種類非常地多，例如：MySQL, PostgreSQL, Interbase, Informix, Oracle, MS SQL 7, Foxpro, Access, ADO, Sybase, DB2 以及一般的 ODBC (其中 PostgreSQL、Informix、Sybase 的driver 是由自由軟體社群發展之後貢獻出來的)。

使用 ADODB 最大的優點之一是：不管後端資料庫如何，存取資料庫的方式都是一致的，開發設計人員不必為了某一套資料庫，而必須再學習另一套不同的存取方法，這大大減輕開發人員的知識負擔，過去的知識往後仍可繼續使用，轉移資料庫平台時，程式碼也不必做太大的更動。

其實 ADODB 這樣的發展理念，並不是首創的，DBI 比 ADODB 出現得更早，它提供 Perl 存取資料庫時，使用一致的 API 呼叫介面。相信用過 Perl + DBI 的朋友，再來用 ADODB 時，會有一種似曾相識的感覺。

另外，ADODB 對用過 ASP 的人而言，應該不陌生，這類朋友對 ADODB 應該很容易接受。

我們來看一下，ADODB 的簡單用法：

<?php

// 引入 adodb 的 inc 檔，才能呼叫 adodb 提供的函式

include('adodb/adodb.inc.php');

// 選擇串連的資料庫種類，以建立聯機對象，

// 一旦對象建立，即可使用其成員函式來處理資料庫。

// 以下 $conn 即此一物件(object)

$conn = &ADONewConnection('mysql');

// 要不要顯示偵錯訊息，false 不要，true 要。

// $conn->debug = false;

$conn->debug = true;

// 串連資料庫

// 用法：$conn->Connect('主機', '使用者', '密碼', '資料庫');

// 用例：

$conn->Connect('localhost', 'piza', 'ooo123', 'test');

// 若欲採用持久性串連，上式可換用 PConnect：

// $conn->PConnect('localhost', 'piza', 'ooo123', 'test');

// 設定 sql 命令

$sql = "insert into t values ('abcde', 18)";

// 執行 sql 命令

$rs = $conn->Execute($sql);

// 檢查執行結果，若 $rs == false，則呼叫 $conn 對象的成員函式 ErrorMsg()

if (!$rs) print $conn->ErrorMsg(); else print "OK!";

?>

結果如下：

---------------------------------------------

(mysql): insert into t values ("abcde",18)

---------------------------------------------

OK!

若把偵錯關掉，即 $conn->debug=false，則結果如下：

OK!

以下，逐步為各位介紹：使用 ADODB 的重點方法。

2. 安裝
ADODB 的首頁在：http://php.weblogs.com/ADOdb，目前(2002/10/24)最新版是：2.42 版，可至 ADODB 下載或至台南縣教網中心 FTP 下載。

安裝 ADODB 的方法超極簡單，只要下載、解壓、放入適當位置，即可完成 ! 如下所示：

1. 下載：

$ ncftp ftp.tnc.edu.tw

cd sysop/ADODB

get adodb242.tgz

2. 解壓：

假設我把 adodb242.tgz 放入 /var/www/html 中

$ cp adodb242.tgz /var/www/html

$ tar xvzf adodb242.tgz

如下所示：

adodb/adodb-cryptsession.php

adodb/adodb-csvlib.inc.php

adodb/adodb-errorhandler.inc.php

adodb/adodb-errorpear.inc.php

adodb/adodb-lib.inc.php

adodb/adodb-pager.inc.php

....以下省略....

現在，您在 /var/www/html/adodb 已安裝好 ADODB 了。

3. 引入 ADODB
一旦安裝好 ADODB，使用前，應把 ADODB 相關的含入檔案引入您的程式中。adodb 目錄放在任何位置無所謂，只要能指向正確路徑檔案名稱即可。一般而言，您的程式碼只須引入 adodb.inc.php。

作法如下：

在您的 PHP 程式中：

include('路徑/adodb/adodb.inc.php');

或

include_once('路徑/adodb/adodb.inc.php');

例：

若您的程式和 adodb 在同一目錄下：

.

..

adodb/

something.php*

則：

include('adodb/adodb.inc.php');

即可。

若位置是在某一個目錄 somedir 中：

.

..

adodb

somedir/something.php

則必須使用：

include('../adodb/adodb.inc.php');

除了 adodb.inc.php 這個含入檔，ADODB 還提供許多 adodb-*.inc.php 的含入檔，這些多半是為驅動某些資料庫的特殊用法而設的。

若是引入 adodb-session.php 則可讓您將 session 存入資料庫中來維護運用。

若是引入 adodb-pager.inc.php，可方便您做分頁顯示。

若是引入 adodb-errorhandler.inc.php，可讓您自訂錯誤處理訊息。

若是含入 adodb-pear.inc.php，可讓您使用 PHP4 的 PEAR DB 文法來使用 ADODB。此時，尚可使用 DSN 串連資料庫的字串設定。如 $dsn="mysql://piza:ooo123@localhost/test";

若是引入 tohtml.inc.php，可幫您在程式碼中，方便將取出的記錄，轉成 HTML 的表格(table)來顯示。

若是引入 toexport.inc.php，可讓您方便地輸出 CSV 檔或以 tab 分隔欄位的資料檔案。

若是引入 rsfilter.inc.php，可讓您在使用記錄之前，預做過濾處理。

若是引入 pivottable.inc.php，可讓您使用 pivot table 功能(俗稱 cross-tabulations)。

注意 ! adodb.inc.php 是一定要引入的，其它，則視您要使用那一個功能，再引入該含入檔即可。

4. 選用資料庫種類，建立聯機對象
由於 ADODB 使用對象導向的作法，因此您在引入檔之後，接著請視您後端資料庫的種類，建立一個聯機對象。作法如下：

以 MySQL 資料庫為例：

$conn = &ADONewConnection('mysql');

註：NewADOConnection 和 ADONewConnection 是一樣的，二者皆可使用。

上例中的 'mysql' 是指資料庫的 drvier 的種類，ADODB 會據此呼叫對應的資料庫 driver。

其它常用的 driver 有：access、ado、ado_access、ado_mssql、db2、vfp、ibase、borland_ibase、informix、imformix72、mssql、oci8、odbc、postgres、postgres64、postgres7、sqlanywhere、sybase....等等。

我們稱建立的對象 $conn 為一 ADOConnection 對象，它代表與資料庫的串連事務，皆透過這個對象來處理。ADOConnection 對象會提供許多處理的方法，以對象導向的說法，這些方法稱為成員函式，這是外界存取此一對象的介面。

一旦聯機對象建立之後，就有許多個物件函式可供您使喚啦 ! 請看下一節的介紹。

5. 偵錯模式
程式開發的過程，為了方便查出出現問題可能的地方，通常我們會開啟偵錯模式，俟程式功能確實穩定之後，再將它關閉。ADODB 提供偵錯模式，存取資料庫時，能顯示其運作方式。

開啟偵錯模式，使用法：

$conn->debug=true

關閉偵錯模式，使用法：

$conn->debug=false

6. 串連資料庫
接著，使用 $conn 聯機對象的 Connect 或 PConnect 函式來串連特定的資料庫，此時必須提供 DSN (Data Source Names)相關資料，DSN 可能包括：主機名稱、資料庫使用者、資料庫密碼、資料庫名稱。不同的資料庫種類，DSN 可能可以省略其中若干項。以 MySQL 而言，則上述四者都要提供。

該函式會傳回 true 或 false，用以表示是否串連成功。

用例：

// 格式：$conn->Connect('主機', '使用者', '密碼', '資料庫');

$conn->Connect('localhost', 'piza', 'ooo123', 'test');

或者，采持久性串連：

// 格式：$conn->PConnect('主機', '使用者', '密碼', '資料庫');

$conn->PConnect('localhost', 'piza', 'ooo123', 'test');

若欲探查是否有聯機成功，可用一個變數來接取傳回值：

$mch="localhost";

$user="piza";

$pwd="ooo123";

$database="test";

$cok = $conn->Connect($mch, $user, $pwd, $database);

或者，采持久性串連：

$cok = $conn->PConnect($mch, $user, $pwd, $database);

if (!$cok) { echo "無法串連資料庫 $database"; exit; }

7. 設定 sql 命令文法、執行 sql 命令
接下來，您就可以設計您要執行的 sql 命令文法，然後付諸執行。

$sql = "這裡放 SQL 的命令文法";

$rs = $conn->Execute($sql);

其中，$rs 為回傳的結果，若 $rs == false，則表示執行失敗，您必須仔細檢查一下。

您不一定要把命令文法放在 $sql 變數中，也可以直接放入 Execute( ) 括弧中。若命令較短無妨，若命令較長，我建議您還是用一個變數 $sql 來設定命令字串吧 !

下一節開始，為各位介紹 SQL 的基本命令，如：Insert、Select、Update、Delete 等等的用法。

8. 插入記錄(Insert)
Insert 的用法如下：

// $name 為字串，$year 為數字

$name='abcde';

$year=18;

// 插入一筆記錄，命令的大小寫無妨，但資料表 t 及變數則大小寫有分別 !

$sql = "INSERT INTO t VALUES ('$name', $year)";

// $sql = "insert into t values ('$name', $year)"; 亦可。

// 執行

$rs = $conn->Execute($sql);

// 檢查執行結果，進行錯誤處理；若正常，則繼續其它動作....

if (!$rs) print $conn->ErrorMsg();

....以下省略....

ErrorMsg() 是錯誤顯示的函式，它會取出錯誤訊息，並顯示出來。

另外，ADODB 提供一種 記錄集(RecordSet) 函式 GetInsertSQL()，可幫您產生 Insert 的文法。

例子如下：

<?php

// 引入 ADODB

include('adodb/adodb.inc.php');

// 建立聯機對象

$conn = &ADONewConnection('mysql');

// 偵錯

$conn->debug=true;

// DSN 四項基本資料設定

$mch="localhost";

$user="root";

$pwd="jack168";

$database="test";

// 串連至資料庫 test

$conn->PConnect($mch, $user, $pwd, $database);

// 產生一筆空記錄

$sql = "select * from t where year=-1";

$rs = $conn->Execute($sql);

// 用一個空數組來裝要更新的資料

$r = array();

$r['name']='john';

$r['year']=28;

// 用 GetInsertSQL 函式來製作一個完整的 sql 命令，此 sql 命令放在 $insertSQL 中

$insertSQL = $conn->GetInsertSQL($rs, $r);

// 執行插入

$conn->Execute($insertSQL);

$conn->Close();

?>

偵錯訊息如下：

-----------------------------------------------------------

(mysql): select * from t where year=-1

-----------------------------------------------------------

(mysql): INSERT INTO t ( name, year ) VALUES ( 'john', 28 )

-----------------------------------------------------------

9. 取出記錄(Select)
Select 的用法如下：

<?php

// 引入 ADODB

include('adodb/adodb.inc.php');

// 建立聯機對象

$conn = &ADONewConnection('mysql');

// 不偵錯

$conn->debug=false;

// DSN 四項基本資料設定

$mch="localhost";

$user="piza";

$pwd="ooo123";

$database="test";

// 串連至資料庫 test

$conn->PConnect($mch, $user, $pwd, $database);

// 執行 Select 由表格 t 取出資料，

// 它會傳回一個 ADORecordSet 記錄集對象 $rs (RecordSet)

// 實際上 $rs 是一個 cursor 指標，它擁有目前的記錄(row 或稱 record)，

// 該記錄的所有欄位資料的內容，存放在 fields 這個數組之中

// ，以數字為索引，第一個由 0 開始

$rs = &$conn->Execute('select * from t');

// 若 $rs 為 false，則秀出錯誤訊息

if (!$rs) {

print $conn->ErrorMsg();

} else {

// 當尚未到達 記錄集 $rs 的結束位置(EOF：End Of File)時，(即：還有記錄尚未取出時)

while (!$rs->EOF) {

// 秀出所有欄位，$FieldCount() 會傳回欄位總數

for ($i=0, $max=$rs->FieldCount(); $i < $max; $i++) {

print $rs->fields[$i] . " ";

}

// 移至下一筆記錄

$rs->MoveNext();

// 換列

echo "<br>\n";

}

}

$rs->Close(); // 可不用

$conn->Close(); // 可不用

?>

$rs->fields[] 數組是由 PHP 的資料庫擴充功能產生的，某些擴充功能並不支援使用欄位名稱當作索引。

若欲使用名稱當作索引，也就是俗稱的 hash 或 associative arrays，則需使用全域變數 $ADODB_FETCH_MODE 加以指定。

以下設定：使用數字索引 $ADODB_FETCH_MODE= ADODB_FETCH_NUM;

以下設定：使用名稱索引 $ADODB_FETCH_MODE= ADODB_FETCH_ASSOC;

下面是使用名稱索引的例子：

<?php

// 引入 ADODB

include('adodb/adodb.inc.php');

// 建立聯機對象

$conn = &ADONewConnection('mysql');

// 不偵錯

$conn->debug=false;

// DSN 四項基本資料設定

$mch="localhost";

$user="root";

$pwd="jack168";

$database="test";

// 串連至資料庫 test

$conn->PConnect($mch, $user, $pwd, $database);

// 執行 sql 之前，指定使用名稱索引

$ADODB_FETCH_MODE = ADODB_FETCH_ASSOC;

// 執行 Select，它會傳回一個 ADORecordSet 記錄集對象 $rs

// 實際上 $rs 是一個 cursor 指標，它擁有目前的記錄內容，

// 該記錄存放在 fields 這個數組之中

$rs = &$conn->Execute('select * from t');

// 若 $rs 為 false，則秀出錯誤訊息

if (!$rs) {

print $conn->ErrorMsg();

} else {

// 當尚未到達記錄集結束位置(EOF)時，

while (!$rs->EOF) {

// 秀出所有欄位

print $rs->fields['name'] . " " . $rs->fields['year'];

// 移至下一筆記錄

$rs->MoveNext();

// 換列

echo "<br>\n";

}

}

$rs->Close(); // 可不用

$conn->Close(); // 可不用

?>

10. 取出記錄(使用 FetchRow)
這裡示範 FetchRow 的用法：

$sql = "select * from t";

$rs = $conn->Execute($sql);

if ($rs) {

while( $ar = $rs->FetchRow() ) {

print $ar['name'] ." " . $ar['year'];

print "<br>\n";

}

}

FetchRow() 會將取出的記錄傳回，您可用一個 array 來接取。

注意 ! 使用 FetchRow() 就不必再用 MoveNext()，FetchRow 內部會自動完成移至下一筆記錄的動作。

11. 更新記錄(Update)
您可以用傳統的方式：

$sql ="UPDATE t SET name='john', year=28 WHERE year=18";

$conn->Execute($sql);

也可以用以下這種方式：

<?php

// 引入 ADODB

include('adodb/adodb.inc.php');

// 建立聯機對象

$conn = &ADONewConnection('mysql');

// 偵錯

$conn->debug=true;

// DSN 四項基本資料設定

$mch="localhost";

$user="piza";

$pwd="ooo123";

$database="test";

// 串連至資料庫 test

$conn->PConnect($mch, $user, $pwd, $database);

// 選擇要更新的那一筆記錄

$sql = "select * from t where year=18";

$rs = $conn->Execute($sql);

// 用一個空數組來裝要更新的資料

$r = array();

$r['name']='john';

$r['year']=28;

// 用 GetUpdateSQL 函式來製作一個完整的 sql 命令，此 sql 命令放在 $updateSQL 中

$updateSQL = $conn->GetUpdateSQL($rs, $r);

// 執行更新

$conn->Execute($updateSQL);

$conn->Close();

?>

偵錯訊息如下：

-------------------------------------------------------------

(mysql): select * from t where year=18

-------------------------------------------------------------

(mysql): UPDATE t SET name = 'john', year = 28 WHERE year=18

-------------------------------------------------------------

12. 刪除記錄(Delete)
刪除記錄很簡單，采傳統方式即可： $sql = "DELETE FROM t WHERE year=18";

$rs = $conn->Execute($sql);

13. 使用欄位對象(Field Objects)
這裡示範欄位對象 FetchField 的用法，用以取得欄位名稱及欄位型態：

$sql = "select * from t";

$rs = &$conn->Execute($sql);

if ($rs) {

while (!$rs->EOF) {

// 取出第二個欄位

$f = $rs->FetchField(1);

// 印出欄位名稱 及 欄位型態

print $f->name . ":" . $f->type;

$rs->MoveNext();

print "<br>\n";

}

}

另外，ADODB 提供一個 RecordSet 函式 MetaType()，可將原始的欄位型態轉成一般型態代碼：

C : 字元

X : text

B : blob

D : 日期

T : timestamp

L : 布爾值或位

I : 整數

N : 數字型態，包括：自動增加、數值、浮點數、實數及整數

R : serial、自動增加

用例：

$f = $rs->FetchField(1);

// 印出欄位名稱 及 欄位型態的代碼

print $f->name . ":" . $rs->MetaType($f->type);

14. 簡單分頁(Pager)
ADODB 提供一種簡單分頁顯示記錄的方法，使用前，要將 adodb-pager.inc.php 引入。

<?php

include('adodb/adodb.inc.php');

// 引入分頁功能

include('adodb/adodb-pager.inc.php');

// 啟動 session

session_start();

$db = ADONewConnection('mysql');

$mch="localhost";

$user="piza";

$pwd="ooo123";

$database="test";

$db->Connect($mch, $user, $pwd, $database);

$sql = "select * from t";

// 產生 pager 對象

$pager = new ADODB_Pager($db, $sql);

// 每一頁秀 5 筆記錄

$pager->Render($rows_per_page=5);

?>

結果如下：

Figure 1. 簡單分頁功能

每頁顯示記錄的數目是由 Render() 來控制的，若沒有傳入指定的 row 數給 Render()，預設值每頁秀 10 筆。

另外，欄位名稱也可以改變，如下示範：

<?php

include('adodb/adodb.inc.php');

// 引入分頁功能

include('adodb/adodb-pager.inc.php');

// 啟動 session

session_start();

$db = ADONewConnection('mysql');

$mch="localhost";

$user="piza";

$pwd="ooo123";

$database="test";

$db->Connect($mch, $user, $pwd, $database);

$sql = "select name as '姓名', year as '年紀' from t";

// 產生 pager 對象

$pager = new ADODB_Pager($db, $sql);

// 每一頁秀 5 筆記錄

$pager->Render($rows_per_page=5);

?>

結果如下：

Figure 2. 改變欄位名稱

15. 輸出 CSV 檔
ADODB 提供輸出 CSV 檔的方法，使用前，要將 toexport.inc.php 引入。

<?php

include('adodb/adodb.inc.php');

// 引入輸出 CSV 檔案功能

include('adodb/toexport.inc.php');

$db = ADONewConnection('mysql');

$mch="localhost";

$user="piza";

$pwd="ooo123";

$database="test";

$db->Connect($mch, $user, $pwd, $database);

$sql = "select name as '姓名', year as '年紀' from t";

$rs = $db->Execute($sql);

// 秀出 CSV 格式

print rs2csv($rs);

?>

結果如下：

姓名,年紀

abcde,45

yyy,20

ppp,34

mmm,13

hhh,41

rrr,65

kkk,29

miso,154

sss,89

abc,18

abcde,0

uyt,58

john,28

也可用 tab 分隔欄位，使用 rs2tab 方法如下：

print rs2tab($rs, false);

注: false 表示不顯示欄位名稱

結果如下：

abcde 45

yyy 20

ppp 34

mmm 13

hhh 41

rrr 65

kkk 29

miso 154

sss 89

abc 18

abcde 0

uyt 58

john 28

若是 print rs2tab($rs, true);

結果如下：

姓名 年紀

abcde 45

yyy 20

ppp 34

mmm 13

hhh 41

rrr 65

kkk 29

miso 154

sss 89

abc 18

abcde 0

uyt 58

john 28

也可以將結果由標準輸出(STDOUT)顯示，使用 rs2tabout 方法如下：

print rs2tabout($rs);

執行結果如下：

Figure 1. 在console中顯示結果

也可以存成 CSV 檔：

// 檔案路徑

$path = "/tmp/test.csv";

// 開檔供寫入

$fhd = fopen($path, "w");

// 若開檔成功

if ($fhd) {

// 則寫入 CSV

rs2csvfile($rs, $fhd);

// 也可以使用 rs2tabfile($rs, $fhd);

// 關檔

fclose($fhd);

}

結果如下：

[ols3@p web]$ cat /tmp/test.csv

姓名,年紀

abcde,45

yyy,20

ppp,34

mmm,13

hhh,41

rrr,65

kkk,29

miso,154

sss,89

abc,18

abcde,0

uyt,58

john,28

16. 取出一定筆數的記錄 (使用 SelectLimit)
ADODB 提供一個 ADOConnect 函式 SelectLimit，可供您取出一定筆數的記錄，用法如下：

$conn->Connect($mch, $user, $pwd, $database);

rs = $conn->SelectLimit("Select * from t", 3, 1);

// 取出 3 筆、在第 1 筆之後

// 秀出這 3 筆記錄

if ($rs) {

while( $ar = $rs->FetchRow() ) {

print $ar['name'] ." " . $ar['year'];

print "<br>\n";

}

}

上式是說：在第 1 筆記錄之後，取出 3 筆，也就是第 2、3、4 筆記錄。

結果如下：
--------------------------------------

(mysql): select * from t LIMIT 1,3

--------------------------------------

注意 ! SelectLimit 的寫法剛好和 MySQL 文法相反 !