多采多姿的程式筆記

要學 PHP 裡的 OOP 時建議

2009-05-06T08:58:00.000-07:00

要學 PHP 裡的 OOP 時建議

之前在 PTT 上寫的，現在轉過來。

要學 PHP 裡的 OOP 時建議

搞清楚為什麼要用 OOP
去用一套 framework 看看別人怎麼設計，要怎麼使用。
等經驗夠了，自己試著設計，一開始當然會做出一堆的廢 class

要知道怎樣的 class 是合適的，沒有練過幾個案子，光看書恐怕很難有心得。我們在使用 PHP 時若要採用 OOP 的話，在實務上有幾個考量：

1. 專案的本質

程式用來解決問題的（若要說是來賺錢的，我也不反對），所以在採用某項技術時都要問一下採用了這技術對於解決問題有幫助嗎？

若決定採用 PHP ，若不是因為只會 PHP 的話（我想這是個爛理由），一定是這個案子使用 PHP 是合適的。

通常什麼情況下 PHP 是合適的呢？它的最大宗的應用還是在網站開發上面。（當然只要是高手， PHP 可以用在很多方面）

我發現若使用 PHP 製作網站，除非是在一定規模的案子中，邏輯有點複雜，，才需要用 OOP 讓物件們互動。

雖然我是個 OO 控，但是我還是得承認，不夠大的案子直接 coding 可能還比較快結束（前提是在不使用任何的 framework 情況下）。

同時我也發現就算在 PHP 中使用了 OOP，若要應付複雜的 business rule 和一些不能夠出錯的場合（如算錢），仍然不太合適，主要原因不是 OOP 的問題，而是出在 PHP 身上，因為 PHP 這語言的設計實在是太隨便了！把持不住的人太容易用 PHP 寫出爛程式，出錯的機會大大的增加，相比之下 Java 就嚴謹多了。這並不是說 Java 不會寫出低安全的東西，而是語言在設計上先天就嚴謹。但是對於純粹的網站開發上，Java 又嫌囉嗦。

若要有良好的錯誤處理的話，我想還是找個 framework 來用會比較好，不然用 PHP 原生的方式處理例外和錯誤相當的累人。

若專案需要採用某個 framework，這時就不得不採用 OOP 了。因為我還沒有見過不使用物件導向技術的 framework

提外話：

若真要應付複雜的 business rule 建議採用 web service將複雜的邏輯包裝起來，而 web service 的內容可以用其它的技術或是讓 PHP 高手來寫，這樣可以降低出錯的機會。

2. 開發人員的功力

說實在的 OOP 沒有那麼好學，若用 C++ 和 Java ，光是要把它們對於 OOP 的語法搞清楚就很累人了，何況還要了解它們的意義！所以要使用 OOP 的話，開發人員要有一定的素質，才能顯出 OOP 的威力。在 PHP 裡使用 OOP ，也一定要把些基本的 OOP 語法學好，說實在話比起其它的語言，PHP裡的語法規則是簡單太多了，若還搞不懂，那就實在是太不用功了。偏偏有耐心學完、搞清楚、把它用上的沒幾個，若你是其中一個恭喜你，這世界用功的人實在太少。若是 OOP 的語法會了，那一些 OO 的原則了不了解？會不會用呢？目前的 framework 中 MVC 架構大行其道，但是 M 是什麼？ V 是什麼？ C 是什麼？它的意義是什麼，開發人員能不能講出在做 OOA&D 時 MVC 是藏在哪裡？M 就一定對到資料庫嗎？ C 應該負責哪些事呢？

在實務中最常見的 OO 原則是單一責任原則，這是一個產生高凝聚力程式碼的方式。這個原則說穿了沒什麼，要了解它也不用五分鐘，但是偏偏很多人不知道也不會用。在不會用這一原則的情況下開發人員很容易的造出了一堆零碎而不好用的 class。

當我看到一張資料表就一個 model，有必要嗎？真正要做的事是什麼？要用的 method 是屬於誰的？了解這些問題， OOP 的威力才出得來。若開發人員造出了一堆零碎而不好用的 class，這樣不僅違反 OO 的規則，維護上還比不使用 OO 還來得麻煩。遇到了這種情況，團隊裡就會有人反彈說為什麼我們要使用 OOP

我們只是做個網站而已，何苦要搞得那麼複雜....

提外話

說起來PHP 是個不算太優雅語言，可能是當初設計時沒想到它會紅，但是紅了以後就又來不及改。相比之下個人覺得同類輕量級語言 python, ruby 都還比它好。但是 OO 功力差的開發人員，給它再好的語言也沒有用 XD

3. 開發團隊

開發團隊在案子進來的時候，就是利用 OOA&D 在進行嗎？ PM

帶頭的 PM 談需求時做得出 USE CASE 嗎？

看得懂 PM 的需求嗎？
有辦法從需求中規劃出所需要的物件嗎？
UML是畫好看的還是真有拿來溝通用？大部份使用 UML 只為了 CMMI，它的價值都沒有被發揮出來。

願意學嗎？

利用PHP用寫Multi Process程式 - 2 使用信號機

2008-01-30T11:00:00.000-08:00

利用PHP用寫Multi Process程式 - 2 使用信號機

2.1 互斥機制

多程序程式設計一定會遇到的問題就是：不同的程序間在兢爭相同的資源。

資源可能是螢幕的輸出或是資料庫的連線。我們不希望兩個以上的程序兢爭螢幕輸出資源，到時可能演變成一個程序輸出兩行而另一個程序再輸出兩行，這樣的輸出是不能看的。

為了解決這個問題，我們必須引入互斥機制，就要有關鍵區域(Critical Area)和信號機(Semaphore）的技術。

在 PHP 下，可以參考官方文件 Semaphore, Shared Memory and IPC Functions

要是以上幾個名詞都忘了的話，再溫習一下作業系統的書吧。

2.2 信號機的使用方式

2.2.1 建立信號機

使用sem_get()可以取得一個新的信號機。

格式

int sem_get (int key [, int max_acquire[, int perm]])

參數

key ：信號機的編號，要是一個還沒有用過的編號。通常使用 ftok() 用來取得
max_acquire ：設定一個信號機可以讓多少程序取用，預設為1
perm ：設定訪問權限

2.2 信號機的使用

2.2.1 建立信號機

使用sem_get()可以取得一個新的信號機。

格式

int sem_get (int key [, int max_acquire[, int perm]])

參數

key ：信號機的編號，要是一個還沒有用過的編號。通常使用 ftok() 用來取得
max_acquire ：設定一個信號機可以讓多少程序取用，預設為1
perm ：設定訪問權限

2.2.2 申請

使用 sem_acquire() 向信號機申請減少一個資源數，並且進入臨界區。

格式

int sem_acquire (int sem_identifier)

參數

sem_identifier：信號機的編號

2.2.3 釋放信號機

使用 sem_acquire() 通知信號機釋放一個資源數，並且離開臨界區。

格式

int sem_release (int sem_identifier)

參數

sem_identifier：信號機的編號

2_3 簡單的範例

<?php
$semid=sem_get( 0xFF3, 1, 0666);
sem_acquire($semid);//向編號為$semid信號機申請進入臨界區
/* 臨界區開始 */
  /*這在裡對共用資源作操作 */
/* 臨界區結束 */
sem_release($semid);//釋放編號為$semid的信號機
?>

2.4 信號機的程式範例

2.4.1 範例

<?php
// 寫兩個子行程搶資源，用semapher做保護
$process_num = 3;
print "老爸：我是老爸，我要生{$process_num}個小孩。\n";
$children = array();
$source_id = ftok('semaghor.php', 'w');
$sem = sem_get($source_id, 1); //取得一個semaphore，可以申請的只有一個

/* 以下要來生小孩 */
$i = 1;
while($i <= $process_num) { 
$pid = pcntl_fork(); //生出一個子程序 
if($pid == -1) { //要是 $pid 是 -1 那就是出錯了  
exit(1); //離開，並且報告出錯 
} else if ($pid != 0) {  //若$pid不是0的話，那就是父行程  
/*這是老爸專區*/  
print "老爸：生了一個第{$i}個孩子，pid是{$pid}\n";  
$children[] = $pid; 
} else { //子程序拿到的 $pid 是 0  
/*這是小朋友區*/  
break; //直接出迴圈 
} 
$i++;
}
if($pid) {  
/* 老爸會進到這裡 */ 
$status = null; 
print "老爸：老爸會等大家玩好才離開\n"; 
foreach($children as $pid) {
//要等每個孩子都離開才離開  
pcntl_waitpid($pid, $status);   
print "老爸：pid是{$pid}的那個孩子，回去時他告訴我他的狀況是{$status}\n"; 
} 
print '老爸也要走了'."\n";
} else { 
/*以下是小朋友遊樂區*/ 
for($j=1;$j<3;$j++)>

2.4.2 執行結果

老爸：我是老爸，我要生3個小孩。
老爸：生了一個第1個孩子，pid是11480
我是第1個小朋友，我是第1次進入了臨界區，我要玩1秒
老爸：生了一個第2個孩子，pid是11481
老爸：生了一個第3個孩子，pid是11482
老爸：老爸會等大家玩好才離開
我是第1個小朋友，要離開臨界區了
我是第2個小朋友，我是第1次進入了臨界區，我要玩2秒
我是第2個小朋友，要離開臨界區了
我是第3個小朋友，我是第1次進入了臨界區，我要玩3秒
我是第3個小朋友，要離開臨界區了
我是第1個小朋友，我是第2次進入了臨界區，我要玩1秒
我是第1個小朋友，要離開臨界區了
我是第2個小朋友，我是第2次進入了臨界區，我要玩2秒
我是第1個小朋友，要走了
老爸：pid是11480的那個孩子，回去時他告訴我他的狀況是0
我是第2個小朋友，要離開臨界區了
我是第3個小朋友，我是第2次進入了臨界區，我要玩3秒
我是第2個小朋友，要走了
老爸：pid是11481的那個孩子，回去時他告訴我他的狀況是0
我是第3個小朋友，要離開臨界區了
我是第3個小朋友，要走了
老爸：pid是11482的那個孩子，回去時他告訴我他的狀況是0
老爸也要走了

利用PHP寫Multi Process程式 1 - 產生子程序

2008-01-24T11:30:00.000-08:00

利用PHP寫Multi Process程式

別問我怎麼會搞到要用 PHP 來寫 multi-process 程式，偏偏最近的案子裡就是有這種需要，不然我也是千百萬個不願意這樣寫…既然資料已經查了一堆，就寫出來給大家看吧。
PS: 預設讀者已知什麼是 multi-process programming ，並且什麼是 pid 。

1.1 產生子程序

1.1.1 產生一個子程序

在PHP裡沒有支援多執行緒編程 (multi-threaded programming) ，因此需要寫類似的功能就必須採取多程序編程 (multi-process programming) 的方式。一般在 unix-like 的作業系統下，要寫多程序程式一定會用到fork。在 PHP 裡也不例外。若要在 PHP 中建一個子程序，要叫用 pcntl_fork()函式。以下是一個簡單的程式樣版：

樣版

<?php
$pid = pcntl_fork(); //在這裡開始產生程式的分岔
if ($pid == -1) {
     die('無法產生子程序');
} else if ($pid) {
     // 父程序會進入這裡
} else {
     // 子程序會進入這裡
}
?>

子程序的 $pid 會是 0
父程序會拿到子程序的 $pid 編號。
pcntl_fork() 函數目前只能在 Unix-like 的作業系統下使用（精確的說是有 System V API 的作業系統）， PHP 目前沒有實作 Windows 環境下的版本。
有關 PHP 裡多程序的其它資料都在 PHP 官方網站上可以找得到。

1.1.2 產生多個子程序

以下這程式會造出多個子程序，子程序造出後父程序會等子程序全都離開後才離開。

範例

<?php
$process_num = 5;
print "老爸：我是老爸，我要生{$process_num}個小孩。\n";
$children = array();

for($i = 1;$i <= $process_num; $i++) {
    $pid = pcntl_fork();
    if($pid == -1) {
        exit(1);
    } else if ($pid) {
    /*這是老爸專區*/
    $children[] = $pid; //紀錄下每個孩子的編號
    print "老爸：生了一個第{$i}個孩子，pid是{$pid}\n";
   } else {
   /*這是小朋友區*/
    break; //直接出迴圈
   }
}
if($pid) { /* 老爸會在這裡休息 */
    $status = null;
    /********************************************************
     * 下面這行的存在意義是：
     *  就算是等所有孩子先行離開以後
     *  父程序才開始等子程序
     *  父程序仍然會知道子程序已離開
     **********************************************************/
    sleep(8); 
    foreach($children as $pid) { //要等每個孩子都離開才離開
        pcntl_waitpid($pid, $status); 
        print "老爸：pid是{$pid}的那個孩子，回去時他告訴我他的狀況是{$status}\n";
    }
    print '老爸也要走了'."\n";
} else {
    /*以下是小朋友遊樂區*/
    print "我是第{$i}個小朋友，我要睡{$i}秒\n";
    sleep($i);
    print "我是第{$i}個小朋友，要走了\n";
    exit(0);
}
?>

解說

在此程式用到了 pcntl_waitpid() ，其參數是子程序的 $pid ，程式執行到此函式時，父行程會等到指定的子程序結束以後才繼續動作。

執行結果

老爸：我是老爸，我要生5個小孩。
我是第1個小朋友，我要睡1秒
老爸：生了一個第1個孩子，pid是10487
我是第2個小朋友，我要睡2秒
老爸：生了一個第2個孩子，pid是10488
我是第3個小朋友，我要睡3秒
老爸：生了一個第3個孩子，pid是10489
我是第4個小朋友，我要睡4秒
老爸：生了一個第4個孩子，pid是10490
我是第5個小朋友，我要睡5秒
老爸：生了一個第5個孩子，pid是10491
我是第1個小朋友，要走了
我是第2個小朋友，要走了
我是第3個小朋友，要走了
我是第4個小朋友，要走了
我是第5個小朋友，要走了
老爸：pid是10487的那個孩子，回去時他告訴我他的狀況是0
老爸：pid是10488的那個孩子，回去時他告訴我他的狀況是0
老爸：pid是10489的那個孩子，回去時他告訴我他的狀況是0
老爸：pid是10490的那個孩子，回去時他告訴我他的狀況是0
老爸：pid是10491的那個孩子，回去時他告訴我他的狀況是0
老爸也要走了

phpDocumentor筆記 - 0 立即體驗

2008-01-22T08:45:00.000-08:00

phpDocumentor筆記 0 立即體驗

0 立即體驗

0 立即體驗 phpDocumentor

這篇原本是我研究 phpDocumentor 的筆記，怎知愈寫愈多，到了後來都變成了一篇教學文件。變成了教程也不錯，這樣之後學的人也輕鬆多了，因為在我研究 phpDocumentor 的過程中，還發現了一些地方 phpDocumentor 的實作和手冊上寫的不太一樣，所以我了花了些時間把官方手冊上的例子一一測過，以下的例子都是在 phpDocumentor v.1.4.1 和 PHP 5.2.1 下可以使用的。若還有錯誤，請通知我<pkwbim.programming@gmail.com>。

0.1 簡介

top

若您已經了解什麼是 phpDocumentor ，可以自行跳過。

你喜歡寫文件嗎？我不喜歡。尤其是在趕工的時候，哪來的美國時間寫文件；就算有時間也是希望趕快把事情做完閃人，怎樣都輪不到寫文件的時候。

文件需要嗎？雖然不喜歡寫文件，但文件真的是必要的。對自己而言，正當在趕案子兵荒馬亂的時候，突然要某個以前寫過的函式結果不知道放哪去了，這時心情會很糟很糟的去把以前的碼挖出來一份一份看，才能找出所要的函式，這樣更浪費時間。對於他人而言，要是每個人寫出來的東西都可以再讓其它人了解，並且進一步使用其它人早已寫好的元件，可以讓我們再省下時間來多喝幾杯咖啡。

那要怎麼樣讓編寫文件輕鬆又自在？ phpDocumentor 就是一個現成好用的工具，只要在寫程式時順手寫上一點點的註解，困難一點的可以再加上一點點的範例。寫完後交給 phpDocumentor 編譯，一下子圖文並茂的程式文件自動就產生了。而且它還不只可以產生 HTML 檔，還可以產生出 PDF, CHM 等文件。就算產生 HTML 檔，還有許多的風格可以選擇。這樣好用的工具放著不用，實在太可惜了。

這份資料裡，只會出現馬上能用的資料，除了這個簡介外，不會廢話太多，所以文件中的文句也冰冷了些。會這樣做的目的是希望文件的每一個部份都能讓讀者快速吸收，任何一個例子複製下來後馬上能用。文件中的每個樣版我都是精心設計過，起碼我以後要用的時候不必再想說要寫一個類別正常需要哪些 Tag ，只要把樣版複製下來以後就直接可以用了。

由於此文件中資料只有使用上最需要的部份（也是一定能用的部份），因此若在使用上想要了解更多，可以到 phpDocumentor 的官方網站 (http://www.phpdoc.org/)上找到所需資料。

此文件中所有的測試環境是 Windows XP + PHP 5.2.1 + phpDocumetor v.1.4.1。

0.2 安裝

top

phpDocumentor 可以用 PEAR 安裝，在這裡也只介紹這種方式。以下是 Windows 版的安裝步驟：

假設你的 php 目錄在 \php5

步驟

安裝 PEAR 基本套件
- 請先查看 \php5\PEAR 裡的內容，若裡面是空的則是還沒安裝 PEAR 基本套件，請以命令列模式下執行 PHP 目錄下的 go-pear.bat。
- 在執行過程中，會要求回答幾個問題，都用預設值即可。
- 執行完畢後會在 \php5\PEAR 下裝了 PEAR 基本套件。
安裝 phpDocumentor
在 PHP 目錄下執行以下命令：
```
\php5\PEAR\pear install -o PhpDocumentor 
```
此命令會安裝 phpDocumentor 及其相依套件。裝好以後， phpDocumentor 的所有程式會放在 \php5\PEAR\PhpDocumentor 裡。

如此就安裝完成。

0.3 改字碼

top

PEAR 有規定，所有的 PEAR 裡的 php 程式都是 iso-8859-1 文件（就是 Latin-1 或「西歐語言」），因此利用 phpDocumentor 產生出的文件，編碼也是預設為 iso-8859-1 。這對使用中文的我們來說很不方便。如果你是和我一樣，不喜歡濫用英文也不喜歡過度強調英文的話，那麼就有需要改變 phpDocumentor 裡的字碼成為 utf-8 使得之後的文件編碼符合我們的需要。

步驟

把 \php5\PEAR\PhpDocumentor\phpDocumentor 裡的（含子目錄）的文件裡的所有 iso-8859-1 的字串全部換成 utf-8 。這種事情我是交給我的文字編輯器 (PSPad) 來做多檔的取代動作。

0.4 一個簡單的範例

top

範例

<?php
/**
* phpDocumentor 使用示範
* 這個檔案是一個簡單的示範
* 內容涵蓋了許多常用的註解方式。
* 有任何的問題請和作者連絡
* @package phpDocumentorExample
* @author 多采多姿 <pkwbim.programming@gmail.com>
* @version 0.1b
*/

/**
* 這是 lib.inc.php 的標題
* 這是 lib.inc.php 的描述
*/
include_once('lib.inc.php');

/**
* 圓周率
* 圓周和直徑的比值
*/
define('pi', 3.14159);

/**
*  這是 funtion1 的註解區塊標題
*  這是 funtion1 的描述
*  @global int 這是函式內第一個全域變數的註解，就是 $global1 的註解
*  @global string 這是函式內第二個全域變數的註解，就是 $global2 的註解
*  @param bool $arg1 這是函式參數 $arg1 的註解
*  @param int|string $arg2 這裡是函式參數 $arg2 的註解
*  @return mixed 傳回值的註解
*/
function function1($arg1, $arg2) {
    global $global1, $global2;
    return array($arg1, $arg2);
}

/**
* 這是MyClass的標題
*
* 建立簡寫型的清單
* 這裡建立一份無序清單
* - 項目一
* - 項目二，
*   每個項目可以是多行，
*   就像這個項目，
*   這行還在項目二中
* - 項目三
* 清單結束，因為沒縮排
* 這裡建立一份有序清單
* 1 有序的項目一，數字後一定要加一個空白。
* 2 有序的項目二
* 有序清單的另一種寫法
* 1. ordered item 1
* 2. ordered item 2
* 清單在此結束
*
* @package phpDocumentorExample
* @author 多采多姿 
* @since 1.0rc1
* @version 0.2b
*
*/
class MyClass {
    /**
     * 這裡是成員變數的註解
     *
     * @var string 成員變數的註解
     * @access private
     */
    private $_variable = "Hello"; 

   /**
    * 這是一個公開的成員函式
    *
    * @param bool $var1 參數1
    * @param string|array $var2 參數1
    * @return void
    * @access public
    */
    public function set_vars($var1, $var2) {
    }
}
?>

0.5 產生文件

top

步驟

將 phpDocumentor 0.4 範例碼存成 example.php 置於 \project\php_project\下。

在命令列下用以下指令

phpdoc --parseprivate -o HTML:frames:earthli -f \project\php_project\example.php -t \project\php_project\docs

或

phpdoc --parseprivate -o HTML:Smarty:PHP -d \project\php_project\ -t \project\php_project\docs

解說
- --parseprivate：是將私有 (private) 成員函式或私有變數等等也都加入程式文件裡。沒有這參數的話，產生出的文件裡只會有公開的 (public) 和受保護的 (protected) 的成員函式和變數。
- -f ：是指針對某個檔案產生註解文件。
- -d ：針對某個目錄（含其子目錄）產生註解文件。
- -t ：指定要輸出的目錄
- -o ：指定輸出格式，上例的格式有兩種
  - HTML:frames:earthli ：是輸出有一種帶有框架 (frame) 的說明文件，所產生出來的文件非常漂亮。Zend Framework 的 API 文件就是採用這種風格。
  - HTML:Smarty:PHP ：產生的文件看起來就像是 PHP 網站上或是 phpDocumentor 官網上的的一樣。

待程式結束後，瀏覽剛剛指定產生文件的目錄下，會有一個 index.html 檔，以瀏覽器打開它就可以看到 phpDocumentor 產生出來的程式文件。倘若在產生文件的過程中，有任何的錯誤，這些錯誤會出現在 error.html檔裡。

phpDocumentor筆記 - 1 馬上能用的基礎

2008-01-21T14:18:00.000-08:00

phpDocumentor筆記

這篇原本是我研究 phpDocumentor 的筆記，怎知愈寫愈多，到了後來都變成了一篇教學文件。變成了教程也不錯，這樣之後學的人也輕鬆多了，因為在我研究 phpDocumentor 的過程中，還發現了一些地方 phpDocumentor 的實作和手冊上寫的不太一樣，所以我了花了些時間把官方手冊上的例子一一測過，以下的例子都是在 phpDocumentor v.1.4.1 下可以使用的。若還有錯誤，請通知我。

1 馬上能用的基礎

1.1. DocBlock

top

在 phpDocumentor 中，每一個註解單位稱為 Documentation block ，簡稱 DocBlock，在此文件裡我稱它為文件區塊。

樣版

基本樣式如下：

/**
* 這是文件區塊 (DocBlock) 的標題
* 第二行開始就是描述
* 描述可以延伸好幾行
*/

解說

文件區塊的開頭一定要有兩個星號（/**），接下來的每一行的開頭要有一個*，結束時使用*/為結尾。
不符合文件區塊格式的註解 phpDocumentor 不會進行處理。
標題只能一行。（官方手冊上是說三行，真莫名其妙）。
標題下一行直接可接描述。（官方手冊上寫一定要空一行，經實驗這是不必要的）
描述是寫詳細解釋的地方，除了可以寫一般的文字外，可以用標籤和 Tag 為文件區塊增加功能。（標籤和 Tag 之後會解釋）
描述可省略。

要為任何一段程式做文件註解，最簡單的方式就是在要解釋的程式之前放一個 DocBlock 。如下所示：

/**
* 這函數叫foo，可能沒有什麼用
*
* 要為一個函數做文件註解，
* 只要在函式之前放一個文件區塊即可
*/
function foo() {
...
}

文件區塊預設是為它接下來的程式區塊做註解，否則會造成誤判。如：

/**
* 這個不是 foo 的文件區塊
*
* 它是 define 的文件區塊
*/
define('DEBUG', 0);
function foo(DEBUG) {
...
}

並不是將 DocBlock 放在任何想要解釋的程式前，它的內容就會出現在 phpDocumentor 所產生的註解文件內。會產生在註解文件內的文件區塊有以下幾類：
1. 檔案層級的文件區塊
2. 引入檔的文件區塊
3. 類別的文件區塊
4. 函式的文件區塊
5. 常數的文件區塊

請注意：若急著使用 phpDocumentor ，那麼不必往下讀，因為讀到這裡已足夠讓 phpDocumentor 產生出程式註解文件來。

1.2 為檔案寫註解

top

每一個檔案的第一個 DocBlock 稱為檔案層級文件區塊 (file-level DocBlock) ，是保留來為檔案寫註解。它一定會有 @package 指出這個檔案是屬於哪個 package 。

樣版

/**
* 這是一個檔案層級文件區塊 (file-level DocBlock)
*
* 這個文件區塊一定要是整份文件的第一個區塊才能夠成為檔案層級文件區塊
* 一定要有 @package 這個 Tag
* @package PackageName
* @author 多采多姿 
* @version 1.0
*/

解說

@package 指出此檔是屬於哪個 package ， package 的名字和程式沒有關係，可以自由指定。指定它的用途只是方便管理檔案，讓相關的檔案在產生的註解文件中可以放一起呈現。
若在其它的文件區塊內沒有另行宣告所屬的 package ，檔案內的所有常數、函式、類別等等，預設會屬於此檔案層級文件區塊內宣告的 package 。
只有在檔案層級的文件區塊和類別所屬的文件區塊裡， @package 才有用。
若一個檔案沒有所屬的 package 時，在產生程式文件時會出現沒有指明 package 的警告訊息。
@author 用來標明這檔案的作者，在作者名字之後可以再接電郵位置，但電郵位置一定要放在 < 和 > 之間。
電郵位置可省略。
@version 用來標明這份檔案的版本。
@version 和 @author不是檔案層級文件區塊內必要的 Tag，但是一般都會提供這兩樣的資訊。

1.3 為常數及變數寫註解

top

PHP 裡變數可大致可分為以下幾類：全域變數、函數參數、函數內變數、類別的靜態成員變數、類別物件的成員變數。這部份只討論全域變數，函數參數的註解方式請參考 1.4 為函式寫註解。

樣版

/**
* 圓周率
* 圓周和直徑的比值
*/
define('PI', 3.14159);

/**
*  這是 funtion1 的註解區塊標題
*  這是 funtion1 的描述
*  @global int 這是函式內第一個全域變數的註解，就是 $global1 的註解
*  @global string 這是函式內第二個全域變數的註解，就是 $global2 的註解
*  @param bool $arg1 這是函式參數 $arg1 的註解
*  @param intstring $arg2 這裡是函式參數 $arg2 的註解
*  @return mixed 傳回值的註解
*/
function function1($arg1, $arg2) {
global $global1, $global2;
/**
* 這註解是不會出現在註解文件裡。
*/
$arg = 3;
return array($arg1, $arg2);
}

解釋

在對常數寫註解，只要在常數前放一個註解文件即可。省略也無妨， phpDocumentor 還是會自動把所有的常數找出來，在註解文件裡整理成表。
在要函式內使用全域變數時，在函式前的文件區塊內使用 @global 即可為全域變數編寫註解。
在@global在使用時不用指明變數名稱，它是依照全域變數在函式內宣告的順序進行註解的判斷。
global $arg1, $arg2;不能拆成兩行寫，也就是說寫成下面的樣子， phpDocumentor 的判斷會出很大的問題。
```
global $arg1;
global $arg2;
```
phpDocumentor 並沒有對於函數內變數特別設計 Tag 來做註解。
$arg3前的文件區塊不會出現在註解文件裡。

1.4 為函式寫註解

top

樣版

/**
* 函式註解格式樣版
*
* fn 是一個function
* @param intstring $arg1 這裡開始寫參數的註解
* @param mixed $arg2 這裡開始寫參數的註解
* @return mixed 這裡可以寫回傳值的註解
*/
function fn($arg1, $arg2) {
...
return $result;
}

解說

@param 用來指出函式參數的型態、變數名和描述。
@return 用來指出函式傳回值的型態和描述。
在描述型態時只能用 PHP 認得的型態，如 int, string, array 等等。
若參數的型態可能有許多種，那就用 mixed 表示。
若型態可能為 int 或 string，那就用連接兩種型態，但請注意 intstring 中間沒有任何空白。
@param 和 @return 中的註解可以省略。

1.5 為類別寫註解

top

樣版

/**
* 這是class1
*
* @package PackageName
* @author Cowboy 
* @since 1.0rc1
* @version 1.9b
*/
class Class1 {
/**
* 這裡是成員變數的註解
*
* @var string 成員變數的註解
* @access private
*/
private $_variable = "Hello";

/**
* 這是一個公開的成員函式
*
* @param bool $var1 參數1
* @param stringarray $var2 參數1
* @return void
* @access public
*/
public function set_vars($var1, $var2) {
...
}
}

解說

Class 1 前的文件區塊裡的 Tag 並不是必要的，但通常會有這幾樣資訊。
雖然檔案層級的文件區塊裡有宣告此檔裡的所有程式是屬於哪個 package ，在類別的文件區塊仍然可以再指定。
@since 指出這類別是從哪個版本以後才加入這個 package 的。
@access 可以用來指定成員的可視程度 (visibility) 。
成員函式的文件區塊部份請參考1.4 為函式寫註解。

1.6 為引入檔案寫註解

top

只要在include_once或require_once前放一個文件區塊即可。

樣版

/**
* 這是 lib.inc.php 的標題
* 這是 lib.inc.php 的描述
*/
include_once('lib.inc.php');

1.7 DocBlock在長描述裡建立簡寫型的清單

top

在DocBlock的長描述裡，我們可以加上- 號建立無序清單，或是以數字1 或1. 建立有序清單。

樣版

/**
* 建立簡寫型的清單
*
* 這裡建立一份無序清單
* - 項目一
* - 項目二，
*   每個項目可以是多行，
*   就像這個項目，
*   這行還在項目二中
* - 項目三
* 清單結束，因為沒縮排
* 這裡建立一份有序清單
* 1 有序的項目一，數字後一定要加一個空白。
* 2 有序的項目二
* 有序清單的另一種寫法
* 1. ordered item 1
* 2. ordered item 2
* 清單在此結束
*/

解說

以- 開頭就可以建立一個無序清單的項目，減號後面一定要接一個空白。
以數字加上點號（例：1. ）或是只有數字（例：1 ），就可以建立有序清單，兩種方式後面都需要加上一個空白。
多行的項目要縮排
若要結束清單，則不縮排直接填內容即可。

Xoops 和 Joomla 只使用 MySQL

2008-01-19T11:59:00.000-08:00

Xoops 和 Joomla 它們都只有支援 MySQL ，偏偏我的客戶使用的是 PostgreSQL ，那就沒有樣法用他們來架站了。不知它們何時才會支援 PostgreSQL 呢？