PHP 內建 ZipArchive 類完整操作指南：壓縮、解壓與進階技巧

PHP 從 5.2.0 版本起內建了 ZipArchive 類，提供了強大的 ZIP 檔案處理能力，無需安裝額外擴展即可實現壓縮、解壓、追加、刪除等操作。本文將系統梳理其核心方法、常見場景與最佳實踐，幫助開發者高效處理壓縮檔案。

環境需求與啟用方式

• PHP 版本：≥ 5.2.0（建議 5.6+ 或 7.x/8.x）
• PECL zip：≥ 1.1.0
• php.ini 設定：確保 extension=zip 已啟用

Windows：在 php.ini 中取消 extension=php_zip.dll 註釋，重啟 Apache/IIS 即可。
Linux：通常預設編譯已包含，若無則透過 yum install php-zip 或 apt-get install php-zip 安裝後重啟 PHP-FPM。

核心功能一覽

1. 解壓 ZIP 檔案到指定目錄
2. 建立新的 ZIP 壓縮包
3. 向現有 ZIP 追加檔案
4. 將整個資料夾遞歸打包（需手動遍歷）
5. 刪除壓縮包內的特定條目
6. 讀取/修改檔案註解、重命名內部檔案

關鍵方法詳細解析

1. open() - 開啟或建立 ZIP 檔案

mixed ZipArchive::open(string $filename [, int $flags ])

常用旗標：

• ZipArchive::OVERWRITE：總是建立新檔，存在則覆蓋
• ZipArchive::CREATE：不存在時建立新檔
• ZipArchive::EXCL：檔案存在則報錯
• ZipArchive::CHECKCONS：檢查一致性

回傳值：成功回傳 TRUE，失敗回傳錯誤代碼（如 ER_NOENT 檔案不存在、ER_OPEN 無法開啟等）。

2. extractTo() - 解壓縮

$zip = new ZipArchive();
$res = $zip->open('test.zip');
if ($res === TRUE) {
    $zip->extractTo('test/'); // 解壓到 test 資料夾
    $zip->close();
} else {
    echo '失敗，錯誤碼：' . $res;
}

3. getNameIndex() / getStream() - 讀取內部檔案資訊與內容

// 取得索引對應的檔名
$name = $zip->getNameIndex(0); // hello.txt

// 取得檔案串流（注意編碼）
$stream = $zip->getStream('hello.txt');
$content = stream_get_contents($stream);

4. renameIndex() / renameName() - 重命名內部檔案

// 依索引重命名
$zip->renameIndex(0, 'newname.txt');

// 依檔名重命名
$zip->renameName('word.txt', 'newword.txt');

5. 註解操作

// 取得壓縮包註解
$comment = $zip->getArchiveComment();

// 設定壓縮包註解
$zip->setArchiveComment('新的壓縮包註解');

6. deleteIndex() - 刪除條目

$zip->deleteIndex(0); // 刪除第一個檔案

建立壓縮包：addFile() 與 addFromString()

$zip = new ZipArchive();
$res = $zip->open('backup.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
if ($res === TRUE) {
    // 從實體檔案加入
    $zip->addFile('data/report.pdf', 'reports/2024_report.pdf');
    // 從字串直接建立檔案
    $zip->addFromString('readme.txt', '這是自動產生的說明文件。');
    $zip->close();
    echo '壓縮完成';
} else {
    echo '建立失敗：' . $res;
}

資料夾遞歸打包範例

function zipFolder($source, $destination) {
    $zip = new ZipArchive();
    if ($zip->open($destination, ZipArchive::CREATE | ZipArchive::OVERWRITE) !== TRUE) {
        return false;
    }
    $source = rtrim($source, '/') . '/';
    $files = new RecursiveIteratorIterator(
        new RecursiveDirectoryIterator($source),
        RecursiveIteratorIterator::LEAVES_ONLY
    );
    foreach ($files as $file) {
        if (!$file->isDir()) {
            $relativePath = substr($file->getPathname(), strlen($source));
            $zip->addFile($file->getPathname(), $relativePath);
        }
    }
    return $zip->close();
}

// 使用
zipFolder('project/', 'project_backup.zip');

常見錯誤碼速查表

最佳實踐提醒

• 操作完成務必呼叫 close() 釋放資源
• 大檔案處理時注意 memory_limit 與 max_execution_time
• 避免在高併發下同時寫入同一 ZIP 檔，建議採用臨時檔 + 原子重命名
• 中文檔名在跨平台（Windows/Linux）時可能出現編碼問題，建議統一使用 UTF-8 或透過 iconv 轉換

掌握 ZipArchive 可讓你在報表匯出、備份系統、插件安裝等場景輕鬆應對。建議結合實際專案多加練習，發掘更多進階用法。