PHP 類庫配置參數設計模式：構造函數注入 vs 設置器注入

場景需求

文件上傳類需配置：上傳大小限制、允許類型、命名規範、目錄創建規則等。

主流設計模式對比

1. 設置器注入（Setter Injection / 屬性配置）

ThinkPHP / Laravel 早期風格

$upload = new UploadFile();          // 實例化
$upload->maxSize = 3145728;          // 3MB
$upload->allowExts = ['jpg','gif','png','jpeg'];
$upload->savePath = './Uploads/images/';
$upload->saveRule = 'uniqid';        // 命名規則
$upload->upload();                   // 執行上傳

• 優點：靈活、可讀性強、支持鏈式調用、可選配置項無需全部設置
• 缺點：對象創建後狀態不完整、難以實現不可變對象

2. 構造函數注入（Constructor Injection）

現代框架（Symfony, Laravel 服務容器）推薦

class UploadFile {
    private $config;
    public function __construct(array $config = []) {
        $this->config = array_merge([
            'maxSize' => 2097152,
            'allowExts' => ['jpg','png','gif'],
            'savePath' => './uploads/',
            'saveRule' => 'md5',
        ], $config);
    }
}

// 使用
$upload = new UploadFile([
    'maxSize' => 5242880,
    'savePath' => './Uploads/avatar/',
]);

• 優點：對象一經創建即處於完整有效狀態、支持不可變對象、依賴關係顯式化
• 缺點：參數多時構造函數筆重、需配合 Builder 模式或配置對象

3. 配置對象模式（Configuration Object / Options Pattern）

參數極多時的最佳實踐

class UploadConfig {
    public int $maxSize = 2097152;
    public array $allowExts = ['jpg','png','gif'];
    public string $savePath = './uploads/';
    public string $saveRule = 'uniqid';
    public bool $createSubDir = true;
}

class UploadFile {
    private UploadConfig $config;
    public function __construct(UploadConfig $config = null) {
        $this->config = $config ?? new UploadConfig();
    }
}

// 使用
$config = new UploadConfig();
$config->maxSize = 5242880;
$config->savePath = './Uploads/avatar/';
$upload = new UploadFile($config);

• 優點：類型安全、IDE 自動補全、文檔化、可驗證、易擴展
• 缺點：增加類定義

4. 靜態工廠方法 + 流式接口

class UploadFile {
    private $config;
    private function __construct() {}
    
    public static function create(): self { return new self(); }
    public function maxSize(int $bytes): self { $this->config['maxSize'] = $bytes; return $this; }
    public function allowExts(array $exts): self { $this->config['allowExts'] = $exts; return $this; }
    public function savePath(string $path): self { $this->config['savePath'] = $path; return $this; }
    public function upload(): array { /* ... */ }
}

// 使用
$result = UploadFile::create()
    ->maxSize(5242880)
    ->allowExts(['jpg','png'])
    ->savePath('./Uploads/avatar/')
    ->upload();

框架實踐參考

選型建議

• 簡單類、配置項少（<5個）：Setter 注入或構造函數注入
• 複雜類、配置項多、需驗證：配置對象模式
• 追求流式 API 體驗：靜態工廠 + 流式接口
• 框架項目：遵循框架慣例（如 Laravel 用配置文件，Symfony 用 OptionsResolver）

核心原則

1. 默認值合理：無配置也能正常工作
2. 驗證儘早：構造時或設置時即驗證，失敗快
3. 文檔化：PHPDoc 標註每個選項含義、類型、默認值
4. 不可變性：配置對象創建後凍結，避免運行時意外修改