PHP 文件上傳類庫設計模式解析：配置驅動、鏈式調用與安全防護

類結構設計亮點

class UploadX {
    // 公開配置屬性 (支持鏈式/直接賦值)
    public $uploadx_form = 'attach';      // 表單字段名
    public $uploadx_save = 'temp';        // 保存目錄
    public $uploadx_type = 'jpg|gif|png|swf|flv|rar|7z|zip|doc|docx|ppt|pptx|xls|xlsx|txt|pdf|wav|mp3|wma|rm|rmvb|wmv';
    public $uploadx_size = '1024';        // KB
    public $uploadx_name;                 // 自定義文件名 (不含擴展名)

    // 內部狀態
    private $uploadx_info = false;
    public $file = [];                    // 結果數組

    public function __construct() { /* 初始化默認值 */ }

    // 核心方法
    public function file() { /* 執行上傳邏輯，返回 bool，結果存入 $this->file */ }
    private function mkdirs($path, $mode = 0777) { /* 遞歸創建目錄 */ }
}

核心流程解析 (file() 方法)

1. 字段存在性檢查：驗證 $_FILES[$this->uploadx_form] 是否存在。
2. 上傳錯誤碼處理：switch ($_FILES[...]['error']) 覆蓋 UPLOAD_ERR_INI_SIZE、UPLOAD_ERR_FORM_SIZE、UPLOAD_ERR_PARTIAL、UPLOAD_ERR_NO_FILE。
3. 擴展名白名單驗證：pathinfo(..., PATHINFO_EXTENSION) 獲取後綴，stripos($this->uploadx_type, $ext) 匹配 (管道分隔字符串)。
4. 文件大小驗證：round($_FILES[...]['size']/1024) > $this->uploadx_size (KB 比較)。
5. 目錄準備：mkdirs() 遞歸創建，支持相對/絕對路徑，自動拼接 $_SERVER['DOCUMENT_ROOT']。
6. 文件名生成：優先使用 $this->uploadx_name + 原擴展名，否則保留原文件名。
7. 移動文件：move_uploaded_file()，失敗檢查路徑/權限。
8. 權限設置：chmod(..., 0777)。
9. 構造結果數組：包含 file(bool), name, path, size, type, time, info。

使用示例

<?php
require_once './libs/uploadx.php';
$upx = new UploadX();
$upx->uploadx_form = 'swfile';
$upx->uploadx_save = "upload";
$upx->uploadx_size = "1024"; // 1MB
$upx->uploadx_name = time(); // 文件名: timestamp.ext

if ($upx->file()) {
    echo "上傳成功<br/>";
    echo "名稱→{$upx->file['name']}<br/>";
    echo "路徑→{$upx->file['path']}<br/>";
    echo "大小→{$upx->file['size']}<br/>";
    echo "類型→{$upx->file['type']}<br/>";
    echo "時間→{$upx->file['time']}<br/>";
    echo "結果→{$upx->file['info']}<br/>";
} else {
    echo $upx->file['info'];
}
?>

設計模式與原則應用

安全性審計與加固建議

現代化重構方向 (PSR-12 / PHP 8.1+)

declare(strict_types=1);

namespace App\Storage;

use Symfony\Component\HttpFoundation\File\UploadedFile;
use Symfony\Component\Validator\Constraints as Assert;

class FileUploader {
    private string $targetDirectory;
    private array $allowedMimeTypes;
    private int $maxSizeBytes;
    private ?string $customNameGenerator = null;

    public function __construct(
        string $targetDirectory,
        array $allowedMimeTypes = ['image/jpeg', 'image/png', 'image/gif', 'application/pdf'],
        int $maxSizeBytes = 2_000_000
    ) {
        $this->targetDirectory = rtrim($targetDirectory, '/');
        $this->allowedMimeTypes = $allowedMimeTypes;
        $this->maxSizeBytes = $maxSizeBytes;
    }

    public function setNameGenerator(callable $generator): self {
        $this->customNameGenerator = $generator;
        return $this;
    }

    public function upload(UploadedFile $file): UploadResult {
        // 1. 原生錯誤碼
        if ($file->getError() !== UPLOAD_ERR_OK) {
            throw new UploadException($file->getErrorMessage(), $file->getError());
        }

        // 2. 真實 MIME 驗證
        $mime = $file->getMimeType();
        if (!in_array($mime, $this->allowedMimeTypes, true)) {
            throw new UploadException("MIME 類型不允許: $mime");
        }

        // 3. 大小驗證
        if ($file->getSize() > $this->maxSizeBytes) {
            throw new UploadException("文件過大: {$file->getSize()} > {$this->maxSizeBytes}");
        }

        // 4. 目錄準備
        if (!is_dir($this->targetDirectory)) {
            mkdir($this->targetDirectory, 0755, true);
        }

        // 5. 生成安全文件名
        $ext = $file->guessExtension() ?? 'bin';
        $name = $this->customNameGenerator 
            ? ($this->customNameGenerator)($file) 
            : bin2hex(random_bytes(16));
        $safeName = "{$name}.{$ext}";
        $targetPath = $this->targetDirectory . '/' . $safeName;

        // 6. 移動 (內部已處理安全檢查)
        $file->move($this->targetDirectory, $safeName);

        // 7. 權限
        chmod($targetPath, 0644);

        return new UploadResult($safeName, $targetPath, $file->getSize(), $mime, time());
    }
}

readonly class UploadResult {
    public function __construct(
        public string $name,
        public string $path,
        public int $size,
        public string $mimeType,
        public int $timestamp
    ) {}
}

總結

UploadX 類展示了經典 PHP 過程式風格的配置驅動上傳封裝，邏輯清晰、功能完整。但面對現代安全威脅 (MIME 偽造、文件名注入、權限過寬) 及 PSR/嚴格類型標準，建議遷移至基於 UploadedFile 物件、強類型、異常驅動、依賴注入友好的現代組件，或直接使用成熟庫 (如 league/flysystem, symfony/http-foundation)。

1. 上一篇文章： PHP 在線圖片裁剪工具全棧實現：前端 Canvas 交互與後端 ImageMagick 處理
2. 下一篇文章： Flash 多文件上傳組件整合指南：前端配置參數詳解與後端 PHP 處理邏輯

PHP 相關知識

自建 PHP 框架：Controller 基類抽象與渲染機制實作

框架核心架構：基類分層、View 渲染、JSON 輸出、路由

Windows 下使用 PHPNow 快速搭建 PHP 開發環境與虛擬主機配置

為什麼選擇 PHPNow？ 手動配置 Apache + PH

用 PHP 建構靜態網站模板框架（四）：輸出緩衝實現「三行接入」完整架構

最終形態：每頁僅三行 PHP <?php requir

關鍵詞匹配項目實戰 Day 12：需求分析與初版方案——從 if-else 走向設計模式的起點

專案脈絡回顧 系列目標：利用淘寶 API 獲取商品標題與屬性