PHP 自定義函數完整教程：聲明、參數、返回值、類型聲明、箭頭函數與最佳實踐

前言

函數是代碼復用核心。PHP 內建 1000+ 函數，但業務邏輯需自定義函數封裝。本文系統講解聲明語法、參數機制、返回類型、變量函數、匿名函數、箭頭函數、現代最佳實踐。

基礎聲明語法

<?php
declare(strict_types=1); // 強制類型模式

// 完整聲明
function functionName(Type $param1, Type $param2 = 'default'): ReturnType {
    // 函數體
    return $result;
}

// 調用
$result = functionName('arg1', 'arg2');

參數機制深度解析

1. 傳值（預設）

function add(int $a, int $b): int {
    return $a + $b;
}

2. 傳引用 &

function swap(&$a, &$b): void {
    [$a, $b] = [$b, $a];
}
$x = 1; $y = 2;
swap($x, $y); // $x=2, $y=1

3. 默認值

function greet(string $name = 'Guest', string $greeting = 'Hello'): string {
    return "$greeting, $name!";
}
// 必須在非默認參數右側
// function bad($a = 1, $b) {} // Fatal Error

4. 可變長參數 ... (5.6+)

function sum(int ...$numbers): int {
    return array_sum($numbers);
}
echo sum(1,2,3); // 6
echo sum(...[4,5]); // 9 (解包數組)

5. 命名參數 (8.0+)

function createUser(string $name, int $age = 18, string $role = 'user'): array {
    return compact('name', 'age', 'role');
}
$user = createUser(name: 'Alice', role: 'admin'); // 跳過 age

返回值與類型聲明

返回多個值的模式

1. 返回數組（傳統）

function stats(array $data): array {
    return [
        'sum' => array_sum($data),
        'avg' => array_sum($data) / count($data),
        'max' => max($data),
    ];
}
['sum' => $s, 'avg' => $a] = stats([1,2,3]); // 解構賦值 7.1+

2. 返回對象/DTO（推薦，類型安全）

readonly class Stats {
    public function __construct(
        public float $sum,
        public float $avg,
        public float $max,
    ) {}
}

function stats(array $data): Stats {
    return new Stats(
        array_sum($data),
        array_sum($data) / count($data),
        max($data)
    );
}
$stats = stats([1,2,3]);
echo $stats->avg;

3. 生成器 yield（大數據/流式）

function readLargeFile(string $path): Generator {
    $fp = fopen($path, 'r');
    while (($line = fgets($fp)) !== false) {
        yield trim($line);
    }
    fclose($fp);
}

foreach (readLargeFile('huge.log') as $line) {
    // 逐行處理，內存常數級
}

匿名函數與箭頭函數

匿名函數 (Closure)

$multiply = function(int $a, int $b): int {
    return $a * $b;
};
echo $multiply(3, 4); // 12

// 綁定外部變量（use）
$factor = 10;
$scale = function(int $x) use ($factor): int {
    return $x * $factor;
};

// 引用綁定（可修改外部）
$counter = 0;
$inc = function() use (&$counter): int {
    return ++$counter;
};

箭頭函數 (fn) (7.4+)

 $x * $factor;
echo $scale(5); // 50

// 多行箭頭函數 (8.1+)
$complex = fn($x) => match (true) {
    $x > 0 => 'positive',
    $x < 0 => 'negative',
    default => 'zero',
};

變量函數與 callable

<?php
function foo() { echo 'foo'; }
$func = 'foo';
$func(); // 調用 foo()

// callable 類型聲明 (8.0+)
function execute(callable $callback, mixed ...$args): mixed {
    return $callback(...$args);
}

execute('strlen', 'hello'); // 5
execute([$obj, 'method'], $arg);
execute(fn($x) => $x * 2, 5); // 10

// Closure::fromCallable (7.1+)
$cl = Closure::fromCallable('strlen');
$cl('test'); // 4

最佳實踐清單

1. 文件頂部 declare(strict_types=1)，全項目統一。
2. 所有函數加完整類型聲明（參數+返回），IDE/靜態分析受益。
3. 單一職責： 函數 < 20 行，超過拆分。
4. 純函數優先： 無副作用、無外部狀態依賴，易測試、易緩存。
5. 不可變參數： 傳值、readonly 屬性，避免意外修改。
6. 命名參數提升可讀性： 參數 > 3 或多默認值時使用。
7. 異常替代錯誤碼： throw new DomainException() 而非返回 false/-1。
8. PHPDoc 註釋： @param @return @throws @deprecated，配合 PHPStan/Psalm。
9. 避免全局函數污染： 用命名空間、類靜態方法、自動載入器。