Zend Framework 驗證器 InArray 陣列成員驗證實作範例

Zend_Validate_InArray：陣列成員資格驗證完整指南

表單驗證中常需檢查輸入值是否在允許清單中 (如角色、狀態、分類等)。Zend Framework 提供 Zend_Validate_InArray 專門處理此類驗證，支援嚴格模式與遞迴搜尋。

基本使用範例

<?php
require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Validate');
Zend_Loader::loadClass('Zend_Validate_InArray');

/**
 * 檢查人員是否在授權名單中
 */
function checkAuthorizedPerson($person) {
    $allowedList = ['張三', '李四', '王五', '趙六', '田七'];
    
    // 建立驗證器
    $validator = new Zend_Validate_InArray($allowedList);
    
    // 執行驗證
    if ($validator->isValid($person)) {
        echo "✅ 授權人員：{$person}";
    } else {
        echo "❌ 未授權人員：{$person}";
        // 取得錯誤訊息
        foreach ($validator->getMessages() as $msg) {
            echo "<br>錯誤: {$msg}";
        }
    }
}

// 測試
checkAuthorizedPerson('張三');  // 通過
echo '<hr>';
checkAuthorizedPerson('王麻子'); // 失敗
?>

建構子參數完整說明

<?php
// 完整建構子簽名
$validator = new Zend_Validate_InArray(
    $haystack,        // 必填：搜尋目標陣列
    $strict = false,  // 選填：嚴格模式 (型別也需相符)，預設 false
    $recursive = false // 選填：遞迴搜尋多維陣列，預設 false
);

// 範例：嚴格模式 - '123' (字串) 不等於 123 (整數)
$validatorStrict = new Zend_Validate_InArray([1, 2, 3], true);
$validatorStrict->isValid('123');  // false
$validatorStrict->isValid(123);    // true

// 範例：遞迴搜尋多維陣列
$multiArray = [
    'admins' => ['root', 'admin'],
    'users'  => ['alice', 'bob']
];
$validatorRecursive = new Zend_Validate_InArray($multiArray, false, true);
$validatorRecursive->isValid('alice');  // true
?>

進階應用：動態驗證清單

<?php
class DynamicRoleValidator {
    private $validator;
    
    public function __construct() {
        // 從資料庫/快取載入最新角色清單
        $roles = $this->fetchActiveRoles();
        $this->validator = new Zend_Validate_InArray($roles);
    }
    
    public function validate($role) {
        return $this->validator->isValid($role);
    }
    
    public function getErrors() {
        return $this->validator->getMessages();
    }
    
    private function fetchActiveRoles() {
        // 模擬資料庫查詢
        return ['super_admin', 'admin', 'editor', 'author', 'subscriber'];
    }
}

// 表單驗證整合範例
$inputRole = $_POST['role'] ?? '';
$validator = new DynamicRoleValidator();

if (!$validator->validate($inputRole)) {
    $errors = $validator->getErrors();
    // 整合到表單錯誤顯示
    foreach ($errors as $error) {
        $form->getElement('role')->addError($error);
    }
}
?>

常見驗證器組合：驗證器鏈

<?php
require_once 'Zend/Validate.php';

// 建立驗證器鏈
$validatorChain = new Zend_Validate();

// 1. 必填驗證
$validatorChain->addValidator(new Zend_Validate_NotEmpty());

// 2. 長度驗證 (2-20 字元)
$validatorChain->addValidator(new Zend_Validate_StringLength(2, 20));

// 3. 字元集驗證 (僅中英數)
$validatorChain->addValidator(new Zend_Validate_Regex('/^[\p{Han}a-zA-Z0-9]+$/u'));

// 4. 白名單驗證
$allowedNames = ['張三', '李四', '王五'];
$validatorChain->addValidator(new Zend_Validate_InArray($allowedNames));

// 執行完整驗證
$input = $_POST['username'] ?? '';
if ($validatorChain->isValid($input)) {
    echo '驗證通過';
} else {
    echo '驗證失敗:<br>';
    foreach ($validatorChain->getMessages() as $msg) {
        echo "- {$msg}<br>";
    }
}
?>

效能優化建議

• 大量資料改用資料庫查詢：白名單超過 1000 筆時，改用 EXISTS (SELECT 1 FROM table WHERE val = ?) 更有效率
• 快取驗證器實例：靜態白名單建立一次驗證器重複使用，避免重複實例化
• 嚴格模式預防型別混淆：數值型欄位建議啟用 $strict = true
• 自訂錯誤訊息：使用 setMessage() 客製化使用者友善提示

自訂錯誤訊息範例

<?php
$validator = new Zend_Validate_InArray($allowedList);
$validator->setMessage(
    '輸入值 "%value%" 不在允許清單中，請選擇：%haystack%',
    Zend_Validate_InArray::NOT_IN_ARRAY
);
// %value% 會被替換為輸入值，%haystack% 為清單字串
?>

Zend_Validate_InArray 簡潔解決白名單驗證需求，配合驗證器鏈能構建完整的輸入防護體系。