PHP ZipArchive 類別完整操作指南：壓縮、解壓、加密與進階技巧

環境需求

• PHP ≥ 5.2.0
• PECL zip ≥ 1.1.0
• php.ini 啟用 extension=zip（Windows 取消 php_zip.dll 註解）

核心功能一覽

1. 解壓縮 ZIP 檔案
2. 建立/新增檔案至 ZIP
3. 追加檔案至現有 ZIP
4. 打包整個目錄（需遞迴處理）
5. 刪除 ZIP 內特定項目
6. 修改 ZIP 內檔案名稱
7. 讀取/設定 ZIP 與檔案註解
8. 取得檔案串流內容（不解壓到磁碟）

常用方法速查表

open() 旗標常數

ZipArchive::OVERWRITE  // 總是建立新檔，覆蓋既有
ZipArchive::CREATE     // 不存在則建立
ZipArchive::EXCL       // 存在則報錯
ZipArchive::CHECKCONS  // 檢查一致性

實戰範例集

1. 解壓縮 ZIP 檔案

<?php
$zip = new ZipArchive();
$res = $zip->open('package.zip');
if ($res === true) {
    $zip->extractTo('/var/www/uploads/extracted/');
    $zip->close();
    echo '解壓完成';
} else {
    echo "開啟失敗，錯誤碼: $res";
}
?>

2. 建立 ZIP 並加入多個檔案

<?php
$zip = new ZipArchive();
$res = $zip->open('backup.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);
if ($res === true) {
    $zip->addFile('/data/config.yaml', 'config.yaml');
    $zip->addFile('/data/database.sql', 'db/backup.sql');
    $zip->addFromString('readme.txt', '此為自動備份，建立時間: ' . date('c'));
    $zip->close();
    echo '備份建立成功';
} else {
    echo "建立失敗: $res";
}
?>

3. 遞迴打包整個目錄（含子目錄結構）

<?php
function zipDirectory($source, $zip, $basePath = '') {
    $source = rtrim($source, '/') . '/';
    $basePath = $basePath ? rtrim($basePath, '/') . '/' : '';

    $iterator = new RecursiveIteratorIterator(
        new RecursiveDirectoryIterator($source, RecursiveDirectoryIterator::SKIP_DOTS),
        RecursiveIteratorIterator::SELF_FIRST
    );

    foreach ($iterator as $file) {
        $relativePath = $basePath . substr($file->getPathname(), strlen($source));
        if ($file->isDir()) {
            $zip->addEmptyDir($relativePath);
        } else {
            $zip->addFile($file->getPathname(), $relativePath);
        }
    }
}

$zip = new ZipArchive();
$zip->open('project.zip', ZipArchive::CREATE);
zipDirectory('/var/www/my-project', $zip, 'my-project/');
$zip->close();
?>

4. 讀取 ZIP 內檔案內容（不寫入磁碟）

<?php
$zip = new ZipArchive();
if ($zip->open('data.zip') === true) {
    $stream = $zip->getStream('config.json');
    if ($stream) {
        $content = stream_get_contents($stream);
        fclose($stream);
        $config = json_decode($content, true);
        print_r($config);
    }
    $zip->close();
}
?>

5. 修改 ZIP 內檔案名稱

<?php
$zip = new ZipArchive();
if ($zip->open('archive.zip') === true) {
    // 依索引重命名
    $zip->renameIndex(0, 'new_first_file.txt');
    // 依名稱重命名
    $zip->renameName('old_name.jpg', 'new_name.jpg');
    $zip->close();
}
?>

錯誤碼對照表

ER_EXISTS      檔案已存在
ER_INCONS      ZIP 檔不一致/損壞
ER_INVAL       無效參數
ER_MEMORY      記憶體配置失敗
ER_NOENT       檔案不存在
ER_NOZIP       非 ZIP 檔案
ER_OPEN        無法開啟檔案
ER_READ        讀取錯誤
ER_SEEK        定位錯誤

進階提示

• 大檔案處理：ZipArchive 需將整個 ZIP 結構載入記憶體，超過 2GB 檔案建議改用 exec('zip ...') 呼叫系統指令
• 加密支援：PHP 7.2+ ZipArchive::setEncryptionName() 支援 AES-256 加密（需 libzip 1.2.0+）
• 記憶體優化：處理大量檔案時，分批 close() 並重新 open() 釋放記憶體
• 權限保留：addFile() 不保留 Unix 權限位，需自行記錄並在解壓後 chmod()

ZipArchive 是 PHP 內建最完整的 ZIP 操作介面，掌握上述核心方法即可應對 95% 的壓縮解壓需求，無需引入第三方函式庫。