PEAR:常用模組_PHP

在上一篇，我們介紹了PEAR的概念，編碼規則，簡單使用方法，你可能對它有了一個初步的瞭解。這次，我們將介紹現有的PEAR庫中的一些模組的功能和它的使用。

在瞭解現有的pear模組之前，我們先瞭解一下PEAR的組織分類方式和命名的約定。PEAR中的模組的組織方式和CPAN類似，每個模組的相關檔案是放在自己的分類目錄下面，有的則是直接放在pear的根目錄下面（單個檔案）。由於PEAR沒有象java那樣的名字空間，所以你的類名應該能夠體現你的模組名或者父類名之間的關係，守一定的約定，比如，你的模組名："Mp3/common",那麼，你的php檔案應該位於：Mp3/common.php,你這個模組的類名應該是：Mp3_common。一般來說，如果你的模組是根據現有的某個模組改進而來的，那麼建議把你的和現有的那個模組放在同一個目錄下面。如果你設計的是一個新的類和模組，你可以自己建立一個新的目錄，或者是按照相似的用途放在同樣的目錄下面。比如，你新編寫了一個模組，用於處理日誌的，建議你把它放在Log/下面，表示是用於Log處理的應用模組；如果新的模組是用於處理mp3的，那麼你可以建立一個新的目錄mp3,放在mp3目錄下面。

由於Pear的大多數模組仍處於開發當中，因此，這裡列舉的是隨著php4.05一起發布的pear中的模組，需要注意的是，一些抽象類別或者是基類(如Mail.php,Log.php,Cache.php)沒有列舉出來，我們只是關注具有具體功能的模組。下面是這些模組的一個列表：

Benchmark/Timer 測試你的一段php代碼的運行效率
Benchmark/Benchmark_Iterate 測試你某個函數迴圈執行時的效能
Cache/Output 可以將你的php指令碼的輸出進行緩衝，可以使用多種方式緩衝（存在檔案，資料庫或者是共用記憶體中）,如果使用這個模組有可能增大伺服器的負載，所以，如果你想通過動態指令碼的緩衝來提供效率，不妨使用Zend optimize,這個模組未必適合
Cache/Graphics 可以將你需要動態輸出的圖片進行緩衝
Console/Getopt 命令列參數的處理模組
CMD 一個虛擬shell，可以用它來運行一些系統的命令
Crypt/CBC 實現Perl Crypt::CBC 模組的模擬
Crypt/HCEMD5 實現Perl Crypt::HCE_MD5 模組的功能

Date/Calc 實現日期的相關操作
Date/Human Human曆法的轉換
DB 提供統一的、抽象的資料庫操作層，後端支援多種資料庫
File/Find 檔案尋找
File/Passwd 操縱password類的檔案，如password,httppass,cvspassword
File/SearchReplace 在檔案中尋找替換字串
HTML/Form 可以在html中快速地建立form
HTML/IT 實現模板定製，動態產生頁面的功能，類似phplib中的模板功能，但是要簡單易用
HTML/ITX 實現對IT的擴充功能，可以更加靈活地定製你的模板，實現更複雜的操作
HTML/Processor XML_Parser的擴充，使之可以應用於html檔案的操作
HTTP/Compress 用於Php 輸出緩衝機制的一個封裝類，同時可以對緩衝的內容進行壓縮儲存
Image/Remote 無需把整個圖片都下載到本地就可以擷取遠端系統的圖片的資訊，
Log/composite Horde對log抽象類別做的一個擴充，可以使多個Tlog對象能夠獲得同一個日誌事件。注意，Log目錄下面的模組都是Horde項目的一部分，大部分都是抽象的超類
Log/file 將日誌資訊寫入檔案
Log/mcal 將資訊發送到本地或遠端的議程管理軟體-mcal的資料庫中
Log/observer Horder中Observer的一個超類
Log/sql 將日誌資訊發送到sql資料庫中
Log/syslog 將資訊發送到syslog中
Mail/RFC822 檢查一個email地址是否是合法的rf822 email地址
Mail/sendmail 使用sendmail來發送信件
Mail/smtp 使用smtp伺服器來發送信件
Math/Fraction 處理分形的數學計算
Math/Util 計算最大公約數
NET/Curl 對php的Curl擴充所作的物件導向的封裝
NET/Dig 操縱dig，進行dns相關的查詢操作
NET/SMTP 使用NET/Socket實現SMTP協議
NET/Socket 通用的Socket類，實現了常用的socket操作的封裝
Numbers/Roman 阿拉伯數字和羅馬數位相互轉換
Payment/Verisign 實現和Verisign支付網關的互動
Pear 提供Pear模組的2個基本類，PEAR 和PEARError類
PEAR/Installer pear的安裝類，提供Perl中的CPAN模組類似的功能
PHPDoc 從php代碼中自動產生API文檔
Schedule/at 和Unix 上的AT守護進程進行互動
XML/Parser 基於php的xml擴充所作的xml的解析器
XML/Render 將xml文檔產生其它的格式（html,pdf),這隻是一個抽象類別，在最新的pear cvs代碼中已經有了html的實現
XML/RPC 用php實現xml-rpc的一個抽象類別，在最新的pear cvs代碼中已經有了xml/RPC/Server的實現

現在我們將簡單地介紹一些比較常用的，而且功能已經比較完善和穩定，可以用於“實戰“模組，其中對於幾個功能很強大的模組Db,phpdoc,XML_Parser，IT,ITX將在以後的文章中單獨介紹。

1.PEAR/Installer
這個模組屬於pear本身的核心模組，它完成pear其它模組的安裝和維護工作，類似perl中的cpan模組的功能，不過目前只有install功能，其它諸如查詢，檢查依賴性等等都沒有完成，pear本身也沒有類似 cpan 那樣的開放的網站，不過隨著參與pear的開發人員的不斷增加，一切都會有的。

使用文法：PEAR_Installer::installer($file)
$file是需要安裝的模組檔案，可以是本地檔案，也可以是遠端檔案，如http://或者是ftp，installer會自動下載到本地。檔案一般使用gzip打包，其中要包括一個package.xml檔案，用於描述你的這個模組的相關資訊，如包含的檔案，相互依賴性等，此外當然要包括你的模組的php檔案。pacakage.xml的DTD檔案在pear目錄下面，名字是package.dtd.

require_once "PEAR/Installer.php";
$installer = new PEAR_Installer;
//安裝指定的模組
$result = $installer->install($package_file);
if ( PEAR::isError($result)){
echo "Install $package_file failed!";
}else {
echo "Install $package_file sucess!";
}
?>

2.CMD
雖然大多數的php應用很少調用系統命令，因為這些應用都是基於web的，從運行效率和系統的負載考慮，都要避免直接調用系統命令，不過，在有些特殊的應用或者是你願意把php作為一個shell工具的時候，調用現有的系統工具就是不可避免的了。CMD可以讓你很方便地執行一系列的系統命令。

使用文法：setOption ($option, $setting)
設定參數$options為$setting

$options是一個常量，它可以是以下值：
CMD_SHUTDOWN : 通過shutdown函數來執行命令
CMD_SHELL : 指定shell的路徑
CMD_OUTPUT : 是否屏蔽命令的標準輸出
CMD_NOHUP : 使用nohup後台執行命令
CMD_VERBOSE : 將錯誤列印到標準輸出

command($command)
添加需要執行的命令，$command可以是數組或普通的字串

exec()
執行已經添加的命令

require_once "CMD.php";
$cmd = new CMD;
$cmd->command('tar zcvf test.tar.gz ~/test');
if ( $cmd->exec() ) {
echo "success！\n";
} esle {
echo "Error:" . $cmd->lastError;
}
?>

3.Benchmark/Timer和Benchmark/Iterate
這2個模組可以讓你測試你的代碼的運行效率如何，我認為這對於系統調試很有用：你可以嘗試不同的演算法，仔細考察每種演算法需要啟動並執行時間，然後選擇最佳的方式。Benchmark/Timer測試回合中在2個不同的時間點的時間差，Benchmark/Iterate則是對Timer擴充，測試回合某段代碼（函數）n次所需要的時間。

使用文法：Benchmark/Timer

Timer::setMarker($name) 設定目前時間點為$name
Timer::start() 開始測試
Timer::stop() 停止測試
Timer::timeElapsed($start = 'Start', $end = 'Stop') 計算$start和$end 這2個時間點的時間差
Timer::getProfiling() 返回start 和 stop 之間所耗用的時間
require_once "Benchmark/Timer.php";
$timer = new Benchmark_Timer;

$timer->start();
$timer->setMarker('Marker 1');
$timer->stop();

$profiling = $timer->getProfiling();
?>

Benchmark/Iterate

Iterate::run()
迴圈運行指定的函數。這是一個具有可變參數的方法，第一個參數是要迴圈的次數，第2個參數是要執行的函數，第3個參數起則是要傳遞給測試函數的參數。

Iterate::get()
返回測試所用的時間

require_once "Benchmark/Iterate.php";

$benchmark = new Benchmark_Iterate;

function foo($string)
{
print $string."
";
}
$benchmark->run(100, 'foo', 'test');
$result = $benchmark->get();
?>

3.File/Find
&glob ($pattern, $dirpath, $pattern_type='php')
在$dirpath中搜尋符合$pattern的目錄和檔案，返回匹配的檔案和目錄名數組

&search ($pattern, $directory, $type='php')
在$directory中搜尋符合$pattern規則的檔案，返回匹配的檔案名稱數組（注意，只是檔案，不包括子目錄）。$pattern是要指定的搜尋條件，一般是規則運算式，$patten_type指定使用什麼模式的規則運算式，預設是php模式，你也可以指定"perl"來使用perl模式的規則運算式

提示：search和glob不同的是，glob並不遞迴搜尋子目錄，而search則遞迴搜尋子目錄。

require_once "File/Find.php";
$find = new File_Find;
//搜尋目前的目錄
$php_files = $find->glob("*php",".");
if ( PEAR::isError( $php_files ) ){
die "錯誤：" . $php_files->getMessage() ."\n" ;
}
//遞迴搜尋目前的目錄
$all_php_files = $find->search("*php",".");
if ( PEAR::isError( $all_php_files ) ){
die "錯誤：" . $php_files->getMessage() ."\n" ;
}
?>

4.File/Passwd
操縱password格式的檔案，類似如標準的unix password,apache 的.htppass,cvs的pserver password檔案。從現有版本的代碼來看，它還不能真正地用來維護這些passwd檔案（比如並不支援shadow)。不過你可以用來建立類似的密碼檔案，當然，安全性不會很高。

使用方法：
File_Passwd($file,$lock=0)----------建立對象，$file是你要操作的passwd檔案，$lock指定是否要用flock對檔案上鎖。
addUser($user,$pass,$cvsuser)----------增加一個使用者,$user,$pass分別是使用者名稱和密碼，$cvsuser是cvs 使用者的id
modUser($user,$pass,$cvsuser)----------修改$user的密碼為$pass,$cvsuser是cvs 使用者的id
delUser($user)----------刪除指定的使用者$user
verifyPassword($user,$pass)----------檢驗使用者密碼
close()----------儲存剛才的修改到password檔案，關閉password檔案，對檔案解鎖。
5.File/SearchReplace
在檔案中尋找和替換字串

使用方法：File_SearchReplace($find, $replace, $files, $directories = '', $include_subdir = 1, $ignore_lines = array())

產生並設定對象

$find
要尋找的字串，可以是字串或規則運算式

$replace
要替換成的字串，可以是字串或規則運算式

$files
指定在哪些檔案中進行替換操作，數組或者是以","分割的一個字串

$directories
指定在那個目錄中操作，可選，數組或者是以","分割的一個字串

$include_subdir
如果是在目錄中操作，指定是否在子目錄中遞迴執行上述操作，可以是數值1或0。

$ignore_lines
指定要忽略的檔案行，這是一個數組，任何以這個數組中任意一個字串開始的檔案行，都會忽略。

getNumOccurences()
返回已經執行了尋找替換的次數

getLastError()
返回上一次的錯誤資訊

setFind($find)
設定要尋找的字串

setReplace($replace)
設定要替換的字串

setFiles($files)
設定要執行替換操作的檔案

setDirectories($directories)
設定要替換操作的目錄

setIncludeSubdir($include_subdir)
設定是否在子目錄中也執行尋找替換

setIgnoreLines($ignore_lines)
設定要忽略的行，只能在使用"normal"搜尋函數的時候使用

setSearchFunction($search_function)
設定要使用的搜尋函數，可以是下列參數：

normal 預設值，使用file函數讀入檔案內容，然後使用str_replace逐行的進行替換。
quick 使用str_replace直接對整個檔案進行替換
preg 使用preg_replace()來進行替換,你可以使用符合這個函數要求的規則運算式
ereg 使用ereg_replace()來進行替換,你可以使用符合這個函數要求的規則運算式

doSearch()
執行尋找替換操作

require_once "File/SearchReplace.php";
require_once "File/Find";

//遞迴搜尋目前的目錄
$find = new File_Find;
$all_php_files = $find->search("*php",".");
if ( PEAR::isError( $all_php_files ) ){
die "錯誤：" . $php_files->getMessage() ."\n" ;
}
if ( !count($all_php_file) ){
die "NO php source files found!\n";
}
//將 $replace = new File_SearchReplace(' $replace->doSearch();
if ( $replace->getLastError() ) {
die "發生錯誤:" . $replace->getLastError() ;
} else {
echo "共成功替換了 " . $replace->getNumOccurences() . " 處。\n";
}
?>

6.HTML/Form
這個模組可以讓你快速地產生一個提交的表單，而無需重新去編寫html代碼

使用方法：Form::HTML_Form($action, $method = 'GET', $name = '', $target = '')

這個類的建構函式帶有一些參數，這些參數和通常要編寫html代碼中的form參數是基本一致的，$action是在form中要提交到的URL,$name可以指定form的名字，$target指定是否要新開視窗等等。

下面的addXXX系列方法，用於在這個form中添加相應的控制項，控制項的屬性和html中的也相一致。
addText($name, $title, $default, $size = HTML_FORM_TEXT_SIZE)
addCheckbox($name, $title, $default)
addTextarea($name, $title, $default,$width = HTML_FORM_TEXTAREA_WT,$height = HTML_FORM_TEXTAREA_HT)
addPassword($name, $title, $default, $size = HTML_FORM_PASSWD_SIZE)
addSubmit($name = "submit", $title = "Submit Changes")
addReset($title = "Discard Changes")
addSelect($name, $title, $entries, $default = '', $size = 1,$blank = '', $multiple = false, $attribs = '')
addRadio($name, $title, $value, $default)
addImage($name, $src)
addHidden($name, $value)

Display()
顯示這個表單

require_once "HTML/Form.php";
//建立並顯示登入表單
$myform = new HTML_Form("./login.php");
$myform->addText('username','使用者名稱','');
$myform->addPasswd('passwd','登入密碼',20);
$myform->addHidden('retry','1');
$myform->addSumit('login','登入');
$myform->Display();
?>

7.Mail/RFC822
檢查一個輸入的email是否合法，不是一件很輕鬆的事情，你也許嘗試使用一些規則運算式來檢查，但是並非那麼方便有效。現在，如果要檢查一系列的郵件地址是否符合RFC822標準，並把它們拆分成單獨的email地址，你可以試試這個模組，非常簡單實用。

使用方法：Mail_RFC822($address = null, $default_domain = null, $nest_groups = null, $validate = null)

類建構函式，$address是你要驗證的一系列的地址，$default_domain，指定預設的網域名稱或者主機名稱，$nest_groups 是否在輸出結果中進行分組，以便顯示$validate 是否需要驗證每個原子parseAddressList($address = null, $default_domain = null, $nest_groups = null, $validate = null)分析驗證所給定的地址清單，如果地址有效，返回拆分後的單獨的地址清單，如果發生錯誤，則返回錯誤資訊。

require_once "Mail/RFC822.php";
$rf822 = new Mail_RFC822;
$result=$rf822->paseAddressList('who;whoim@hotmail.com;test@test.ch');
if ( $rf822->error ){
echo "Error:$result";
}else {
reset($result);
for ($i=0; $i< count($result);$i++){
echo "email:$result[$i]\n";
}
}
?>

8.Mail/Sendmail
sendmail是unix/linux上面最常用的MTA,這個模組可以讓你直接使用sendmail來發送信件

使用方法：Mail_sendmail($params)

類建構函式，$params是一個關聯陣列,你可以設定sendmail的參數，目前只有'sendmail_path'是有效，用來設定sendmail的路徑 send($recipients, $headers, $body) 發送信件，$recipients是你的收件者的email地址，可以是單個，也可以是用;隔開的地址清單，只要符合RFC82標準就可以。$headers是你發送信件的信頭，這是一個關聯數租，數組的關鍵字是信頭的名字（如Subject)，數組值則是信頭的值(比如：Hello!)。處理後的信頭將會是：Subject:Hello! $body 是信件的信體，包括所有的MIME編碼後的部分。如果成功，返回真，否則返回一個PEAR_Error對象

require_once "Mail/sendmail.php";
$sendmail = new Mail_sendmail(array('sendmail_path=>'/usr/local/bin/sendmail'));
$header = array('Subject'=>'Hello','BCC'=>'test2@hotmail.com');
$body = 'This is a test message from nightsailer.com';
$result = $sendmail->send('test@nightsailer.com', $header, $body);
if ( PEAR::isError($result) ){
echo " 發送失敗 原因：".$result->getMessage()."";
}else {
echo "恭喜！發送成功！";
}
?>

9.Mail/smtp
對於現在有些網站不允許使用sendmail,那麼如果你的php程式希望使用發信功能，就需要能夠通過使用外部的smtp伺服器來完成相應的功能了。

使用方法：使用上這個模組和Mail::sendmail基本上是一樣的。需要注意的是：這個模組需要使用Net::SMTP模組：Mail_smtp($params)
$params的有效參數是：
'host' smtp的伺服器位址，預設是 localhost
'port' smtp服務連接埠，預設是25
'auth' smtp是否需要授權驗證，預設是false
'usename' smtp授權的使用者名稱
'password' smtp授權的密碼

send($recipients, $headers, $body)
發送

require_once "Mail/sendmail.php";
$params=array('host'=>'smtp.nightsailer.com','auth'=true,
'username'=>'night','password'=>'123456');
$sendmail = new Mail_sendmail($params);
$header = array('Subject'=>'Hello','BCC'=>'test2@hotmail.com');
$body = 'This is a test message from nightsailer.com';
$result = $sendmail->send('test@nightsailer.com', $header, $body);
if ( PEAR::isError($result) ){
echo " 發送失敗 原因：".$result->getMessage()."";
}else {
echo "恭喜！發送成功！";
}
?>

10.Schedule/At
這個模組提供了unix上面的at程式的介面

add($cmd, $timespec, $queue = false, $mail = false )
追加一個at命令

這個方法將為at程式產生一個定製的作業:
$cmd 是你要啟動並執行程式或指令碼
$timespec 是作業開始執行的時間，格式與at要求的相同
$queue 選擇性參數，指明作業的隊列名
$mail 選擇性參數，指明是否在作業結束後要發送email彙報運行結果

show($queue = false)
顯示在at隊列中的命令，返回一個關聯陣列，數組的key是作業的編號，相應的索引值也是一個關聯陣列，內容是array（runtime，queue）$queue是一個選擇性參數，你可以用它限定只返回隊列中隊列名匹配$queue的作業列表

remove($job = false)
從at隊列中刪除指定的at作業$job是要刪除的作業編號,如果，成功，返回true,否則返回false

require_once "Schedule/At.php";
$at = new Schedule_At();
//產生並追加一個作業
$result = $at->add ('find / -type file -name core -exec rm -f {} \;','00:00');
if ( PEAR::is_Error($result) ) {
echo "無法追加作業！\n";
echo "原因：$result->getMessage() \n";
exit;
}
//顯示當前at隊列
$queue = $at->show();
if ( PEAR::isError($queue) ) {
echo "發生錯誤！\n";
echo "原因：" . queue->getMessage(). "\n";
exit;
}
reset( $queue );
while ( list($job, $cmd) = each $queue ){
echo "[$job]" . $cmd['runtime'] . "-" .$cmd['queue']；
echo "\n"
}
?>

以上是一些PEAR模組的使用，更為詳細的說明需要你自己去察看這些模組的源檔案，或者你可以使用phpdoc自動產生這些模組的api文檔。關於phpdoc,我們將在下篇詳細討論。

