PEAR 套件安裝與核心庫實戰：從環境部署到 HTML_QuickForm 快速開發

Linux/macOS (推薦系統包管理器)

# Debian/Ubuntu
sudo apt-get install php-pear

# CentOS/RHEL
sudo yum install php-pear

# macOS (Homebrew)
brew install php@8.2  # 內建 pear
# 或單獨安裝
php /usr/lib/php/install-pear-nozlib.phar

手動修正 include_path（若自動配置失效）

; php.ini
; Windows
include_path = ".;D:\php\includes;D:\php\PEAR"
; Linux/macOS
include_path = ".:/usr/share/php:/usr/local/lib/php/pear"
; 重啟 Web 服務 / php-fpm 生效

二、PEAR 命令行管理速查表

三、PEAR 核心庫分類導覽（精選 10 類）

四、實戰：HTML_QuickForm 10 分鐘構建登錄表單

1. 安裝依賴

pear install HTML_QuickForm
# 若需 HTML_QuickForm2 (PHP5.2+)
pear install HTML_QuickForm2

2. 核心代碼

<?php
require_once 'HTML/QuickForm.php';

// 1. 實例化表單對象
$form = new HTML_QuickForm('loginForm', 'post', $_SERVER['PHP_SELF']);

// 2. 添加頁首標題組
$form->addElement('header', null, '會員登錄系統');

// 3. 添加輸入字段（自動生成 label、id）
$form->addElement('text', 'username', '用戶名：', ['size' => 20, 'maxlength' => 50]);
$form->addElement('password', 'password', '密碼：', ['size' => 20, 'maxlength' => 50]);

// 4. 添加驗證規則（服務端 + 客戶端 JS 同步生成）
$form->addRule('username', '用戶名不能為空', 'required');
$form->addRule('username', '用戶名長度 3-20 字符', 'rangelength', [3, 20]);
$form->addRule('password', '密碼不能為空', 'required');
$form->addRule('password', '密碼長度 6-30 字符', 'rangelength', [6, 30]);

// 5. 添加提交按鈕
$form->addElement('submit', 'submit', '登錄');

// 6. 處理提交
if ($form->validate()) {
    $values = $form->getSubmitValues();
    // 業務邏輯：驗證用戶、設置 Session、重定向...
    echo "<div class='success'>歡迎回來, {$values['username']}!</div>";
    // 實際項目中應 header('Location: dashboard.php'); exit;
}

// 7. 渲染輸出（預設表格佈局，可替換渲染器）
$form->display();
?>

3. 進階：自定義渲染器（Bootstrap 5 風格）

require_once 'HTML/QuickForm/Renderer/Array.php';
$renderer = new HTML_QuickForm_Renderer_Array();
$form->accept($renderer);
$formData = $renderer->toArray();
// 在模板中遍歷 $formData 生成任意 HTML 結構
// 如: <div class="mb-3"><label class="form-label">{label}</label>{element}<div class="text-danger">{error}</div></div>

4. 關鍵優勢回顧

• 定義即驗證：字段與規則綁定，消除「驗證邏輯與表單結構分離」的維護痛點。
• 雙端驗證同步：$form->getValidationScript() 生成對應 JS，服務端/客戶端規則**單一來源**。
• 渲染器模式：邏輯與表現徹底分離，支援 Table、Array、CSS、Smarty、Twig 等多種輸出。
• 凍結/鎖定狀態：$form->freeze() 將表單轉為只讀顯示（詳情頁復用同一定義）。

五、避坑與最佳實踐

• ⚠️ 版本鎖定：pear install HTML_QuickForm-3.2.16 避免非預期升級破壞相容性。
• ⚠️ 命名空間隔離：PEAR 套件無命名空間，專案引入時注意類名衝突（如自定義 Log 類）。
• ✅ 併用 Composer：composer require pear/html_quickform2 (官方映射包) 統一依賴管理。
• ✅ 單元測試覆蓋：使用 pear run-tests 確保升級不破壞業務邏輯。

結語

PEAR 或許不再是主流包管理器，但其留下的**工程化基因**——標準化結構、嚴格測試、文檔優先、向後相容——依然值得每位 PHP 開發者學習。掌握 PEAR 核心庫，能在維護舊系統、快速構建內部工具、受限環境（無 Composer/網絡）時成為你的「秘密武器」。