NetBeans 製作 PHP 說明文件

開發同時兼顧編寫清楚的說明文件，並不容易，甚至製作範例更加麻煩
Java 的 JDK 開發工具提供 javadoc 這種可以直接將源始碼上的特定備註語法轉換成 HTML 說明文件，既方便又快捷
那 PHP 有冇類似的工具能方便製作說明文件？

PHP 有一些第三方工具能協助 PHP 專案製作說明文件，例如： ApiGen, PHPDocumentor
ApiGen 及 PHPDocumentor 都能支援 NetBeans
ApiGen 可以在 apt-get 等系統管理工具上獲得
而 PHPDocumentor 則需要通過 PEAR 安裝或自行到官方網頁下載及設定
兩者使用上都非常相似，但在下覺得由 ApiGen 製作的說明文件閱讀上方便點，所以主要介紹 ApiGen


先在 NetBeans 安裝 PHP 及 ApiGen 等外掛程式


在需要製作文件的 PHP 專案展開選單，點選 Generate Documentation 項目


雖然 NetBeans 已經安裝 ApiGen 外掛，但仍然需要系統中有 ApiGen 的執行程式


在 Terminal 輸入

sudo apt-get install php-apigen

安裝 ApiGen


到 Tools > Options > PHP > Framework & Tools
若按下之前 NetBeans 出現未設定 ApiGen 的錯誤，會自動跳至設定頁面
按下 ApiGen Script 的 Browse 按鈕


安裝後 ApiGen 的執行程式放在 /usr/bin/apigen


亦可以在文字欄位中直接輸入 ApiGen 的執行路徑


設定專案的文件輸出目錄


建立文件輸出目錄


選擇文件輸出位置


確定文件輸出位置


ApiGen 需要 PHP 的執行程式才能執行


在 Terminal 輸入

sudo apt-get install php

安裝 PHP


到 Tools > Options > PHP > Framework & General
若按下之前 NetBeans 出現未設定 PHP 的錯誤，會自動跳至設定頁面
按下 PHP * Interpreter 的 Browse 按鈕


安裝後 PHP 的執行程式放在 /usr/bin/php


同樣，亦可以在文字欄位中直接輸入 PHP 的執行路徑


再次在 PHP 專案展開選單，點選 Generate Documentation 項目
但發現錯誤，並建議在指令加上 --debug 除錯


到專案的目錄，執行剛才的指令並加上 --debug
出現 /usr/share/php/FSHL/autoload.php 找不到 /usr/share/php/FSHL/FSHL-2.1.0/FSHL/Lexer/Php.php 的錯誤


但 /usr/share/php/FSHL 及 /usr/share/php/FSHL/Lexer 的檔案結構
與 /usr/share/php/FSHL/FSHL-2.1.0/FSHL/Lexer/Php.php 相似


因此查看 /usr/share/php/FSHL/autoload.php 內容
發現 /usr/share/php/FSHL/autoload.php 的類別的路徑稍有不同，因此進行修改
在 function($class) 中加入 $fshl_dir = '' 的路徑
然後將所有 '/FSHL-2.1.0/FSHL 取代成 $fshl_dir . '
其實可以直接將所以 /FSHL-2.1.0/FSHL 刪除即可，但在下認為以 變數 保存可以方便日後再次修改


完成後儲存檔案
(不一定使用 vim ，用任何閣下方便的文字編輯文件便可以)


執行指令，出現 Call to undefined function ApiGen\Charset\Configuration\mb_list_encodings() 錯誤


在 Terminal 輸入

sudo apt-get install php-mbstring

安裝 PHP 的 mbstring 函式庫


執行指令，能運行到部分，但出現 call to undefined function Latte\Runtime\utf8_decode() 錯誤


在 Terminal 輸入

sudo apt-get install php-xml

安裝 PHP 的 xml 函式庫


再次執行指令終於沒有錯誤


再到 PHP 專案展開選單，點選 Generate Documentation 項目
終於能在 NetBeans 中正常運作


建立的 PHP 文件的樣式類似由 javadoc 建立的 Java 文件


在 PHP 專案展開選單，點選 Properties 項目


在 Documentation 選項，還有其他設定
有需要可以調整文件輸出的項目

如果閣下架設典型的 LAMP ，在安裝時已經會將 php-xml 、 php-mbstring 安裝，只需要再安裝 php-apigen 便完成
如果 PHP, ApiGen 執行程式比 NetBeans 的 PHP, ApiGen 外掛程式先安裝，NetBeans 在安裝外掛後會自動尋找對應的執行程式