PHP 從外部獲取函數參數個數：func_num_args 限制與 Reflection 解決方案

func_num_args()、func_get_arg()、func_get_args() 是 PHP 內建的「函數內部」檢查實際傳入參數的函數族，**只能在函數內部調用**，外部直接呼叫會報錯。若需在「外部」（調用前、裝飾器、路由解析、文檔生成）獲取函數定義的參數資訊，必須使用 Reflection API。

func_num_args() 的侷限性演示

<?php
function war($a, $b, $c) {
    echo "內部調用 func_num_args(): " . func_num_args() . "\n"; // 3
}

war(1, 2, 3);

// 外部直接調用 → Fatal Error
// echo func_num_args(); // 錯誤：Cannot be used outside of a function

ReflectionFunction / ReflectionMethod 完整解決方案

1. 獲取參數總數（含可選參數）

<?php
function war($a, $b, $c = 'default', ...$rest) {}

$ref = new ReflectionFunction('war');
echo "參數總數: " . $ref->getNumberOfParameters() . "\n"; // 4 (a, b, c, ...$rest)
echo "必填參數數: " . $ref->getNumberOfRequiredParameters() . "\n"; // 2 (a, b)

2. 遍歷參數詳細資訊

<?php
function apiUserCreate(string $name, int $age = 18, array $tags = [], ?string $note = null) {}

$ref = new ReflectionFunction('apiUserCreate');
foreach ($ref->getParameters() as $param) {
    echo "參數名: {$param->getName()}\n";
    echo "  是否必填: " . ($param->isOptional() ? '否' : '是') . "\n";
    echo "  是否可變參數: " . ($param->isVariadic() ? '是' : '否') . "\n";
    echo "  是否傳引用: " . ($param->isPassedByReference() ? '是' : '否') . "\n";
    echo "  預設值: " . ($param->isDefaultValueAvailable() ? var_export($param->getDefaultValue(), true) : '無') . "\n";
    
    // 類型提示 (PHP 7+)
    $type = $param->getType();
    if ($type) {
        echo "  類型: " . $type->getName() . ($type->allowsNull() ? '|null' : '') . "\n";
        echo "  內建類型: " . ($type->isBuiltin() ? '是' : '否') . "\n";
    }
    
    // 屬性 (PHP 8+)
    if ($param->getAttributes()) {
        foreach ($param->getAttributes() as $attr) {
            echo "  屬性: " . $attr->getName() . "\n";
        }
    }
    echo "\n";
}

3. 類方法同樣適用

<?php
class UserService {
    public function create(string $name, int $age = 18): User {}
    protected function notify(string $event, array $payload = []): void {}
}

$refMethod = new ReflectionMethod(UserService::class, 'create');
echo "create() 必填參數: " . $refMethod->getNumberOfRequiredParameters() . "\n"; // 1

實戰應用場景

效能考量與快取策略

Reflection 涉及內部結構遍歷，比直接調用慢 10-100 倍。**生產環境必須快取**：

<?php
class ReflectionCache {
    private static array $cache = [];
    
    public static function getParameters(string $class, string $method): array {
        $key = $class . '::' . $method;
        if (!isset(self::$cache[$key])) {
            $ref = new ReflectionMethod($class, $method);
            self::$cache[$key] = $ref->getParameters();
        }
        return self::$cache[$key];
    }
    
    // 生產環境建議用 APCu/Redis 做跨進程快取
}

替代方案：DocBlock 註解解析（舊專案兼容）

PHP 5 時代無類型提示，常用 @param 註解：

<?php
/**
 * 建立用戶
 * @param string $name 用戶名
 * @param int $age 年齡
 * @param string[] $tags 標籤
 * @return User
 */
function createUser($name, $age = 18, $tags = []) {}

解析庫：phpdocumentor/reflection-docblock，現代專案建議直接用原生類型提示 + Reflection，避免註解與代碼不同步。

總結

• func_num_args() 只能在**函數內部**獲取**實際傳入**參數數
• 外部獲取**定義時**參數資訊（名稱、類型、預設值、屬性、必填性）→ **ReflectionFunction/ReflectionMethod**
• 生產環境**必須快取** Reflection 結果
• PHP 8+ 類型系統 + Attributes 讓 Reflection 成為靜態分析、框架基礎設施的核心支柱