登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  文章 >  php教程

PHP ZipArchive::setCompressionName 怎样单独调整文件压缩级别

来源:17golang原创

时间:2026-11-18 02:25:43 498浏览 收藏

可以。ZipArchive::setCompressionName() 会按 ZIP 内部条目的名称定位一个文件,再为它设置压缩方法和压缩级别。最稳妥的顺序是:先 open(),再用 addFile() 或 addFromString() 创建条目,然后调用 setCompressionName(),最后检查 close() 是否成功。

官方文档:https://www.php.net/manual/en/ziparchive.setcompressionname.php

这个方法返回布尔值,但它只说明“调整条目属性的请求是否被接受”。归档最终是否成功写入磁盘,还要看 close() 的返回值。

方法签名和参数分别做什么

方法签名是 setCompressionName(string $name, int $method, int $compflags = 0): bool。其中 name 是 ZIP 内部的条目名,不一定等于本地文件路径;method 使用 ZipArchive::CM_* 常量;compflags 是压缩级别参数,具体作用取决于所选压缩方法。

因此,addFile('/data/report.txt', 'docs/report.txt') 之后,应传入 docs/report.txt,而不是 /data/report.txt。名称不匹配时,方法可能返回 false,代码不应继续假设设置已经生效。

PHP ZipArchive 按 ZIP 内部名称设置单个条目压缩方法的关系说明图
图1:说明图。外部文件路径先进入 ZIP 内部名称,setCompressionName 再按内部名称选择单个条目的压缩方法;这不是运行截图。

按 ZIP 内部名称单独设置压缩

下面的例子让文本条目使用 DEFLATE,并把图片条目保持为 STORE。文本通常适合压缩,已经压缩过的图片则可以避免重复压缩带来的时间开销。这里的数值只是示例配置,部署时应按压缩方法和业务目标选择。

open(__DIR__ . '/bundle.zip', ZipArchive::CREATE | ZipArchive::OVERWRITE);

if ($openResult !== true) {
    // open() 返回错误码时不要继续操作未打开的归档。
    throw new RuntimeException('ZIP 打开失败,错误码:' . $openResult);
}

try {
    // 第二个参数是 ZIP 内部名称,后续按名称设置压缩时必须使用它。
    if (!$zip->addFromString('docs/readme.txt', "说明文本\n")) {
        throw new RuntimeException('添加文本条目失败');
    }

    if (!$zip->addFile(__DIR__ . '/photo.jpg', 'assets/photo.jpg')) {
        throw new RuntimeException('添加图片条目失败');
    }

    // 文本条目使用 DEFLATE;compflags 的含义由压缩方法决定。
    if (!$zip->setCompressionName('docs/readme.txt', ZipArchive::CM_DEFLATE, 6)) {
        throw new RuntimeException('设置文本压缩失败');
    }

    // 已经压缩过的图片示例使用 STORE,避免再次压缩。
    if (!$zip->setCompressionName('assets/photo.jpg', ZipArchive::CM_STORE)) {
        throw new RuntimeException('设置图片压缩失败');
    }

    // close() 才会把内存中的归档修改写入磁盘,必须单独检查结果。
    if (!$zip->close()) {
        throw new RuntimeException('ZIP 最终写盘失败');
    }
} catch (Throwable $error) {
    // close() 未执行时显式关闭对象,避免把失败状态误当成成功。
    $zip->close();
    throw $error;
}

echo 'ZIP 已生成';
?>

为什么要区分本地路径和 entry name

addFile() 同时接收本地路径和可选的 ZIP 内部名称。内部名称是归档结构的一部分,允许你把不同目录的本地文件放入统一的归档层级。setCompressionName() 只看这个归档层级里的名称,所以应把名称集中定义,避免后续修改路径后忘记同步压缩配置。

如果条目来自 addFromString(),它本来就没有独立的本地文件路径,传给 setCompressionName() 的仍然是 addFromString() 的第一个参数。对于包含目录的名称,建议统一使用正斜杠,例如 docs/readme.txt。

按名称设置和按索引设置有什么区别

setCompressionName() 适合你已经知道归档内名称的场景,可读性更好,也不依赖条目插入顺序。setCompressionIndex() 则按条目索引定位,适合你正在遍历索引或已有稳定索引的处理逻辑。两者的 method、compflags 和布尔返回值语义相近。

setCompressionName('docs/readme.txt', ZipArchive::CM_DEFLATE, 6);

// 只有在处理索引列表时才使用按索引方式;索引变化后要重新确认目标条目。
$indexOk = $zip->setCompressionIndex(0, ZipArchive::CM_DEFLATE, 6);

// 两个方法都可能返回 false,调用方应把失败转换成可处理的错误。
if ($nameOk !== true || $indexOk !== true) {
    throw new RuntimeException('条目压缩设置未全部成功');
}
?>

最容易忽略的是 close 的最终写盘边界

ZipArchive 的添加、删除和压缩属性修改先保存在对象状态中,文件系统相关错误可能直到 close() 才暴露。例如目标目录没有写权限、磁盘空间不足,或者归档文件无法替换时,前面的 addFile() 和 setCompressionName() 都不能替代最终写盘检查。

生产代码至少要分开检查三类结果:归档是否打开、条目是否加入、压缩设置和最终关闭是否成功。不要只因为方法没有抛出异常,就把输出文件当成已经可交付。

PHP ZipArchive 从内存修改到 close 最终写盘及失败处理的关系说明图
图2:结构图。添加条目和调整压缩参数先停留在归档对象中,close 才写盘并暴露部分文件系统错误;这不是运行截图。

使用时的三个边界

  • 名称边界:传入 ZIP 内部名称,不要把本地绝对路径当成 name。
  • 方法边界:compflags 不是所有压缩方法都用同样方式解释,先确定 CM_* 方法再决定级别。
  • 保存边界:调整成功不等于文件已经落盘,必须检查 close() 的布尔结果。

常见问题

setCompressionName 找不到条目怎么办?

先打印或记录加入 ZIP 时使用的内部名称,确认大小写、目录前缀和扩展名完全一致。不要用本地文件路径替代内部名称。

应该传压缩级别还是压缩方法?

第二个参数先传 ZipArchive::CM_* 方法,第三个参数才是可选的 compflags。两者职责不同,不能把级别值放到第二个参数。

为什么 close 也要判断?

因为归档修改可能仍在内存中,close() 负责最终写盘;权限、目录和磁盘等错误可能到这个阶段才返回失败。

参考资料:https://www.php.net/manual/en/ziparchive.setcompressionindex.php;https://www.php.net/manual/en/ziparchive.addfile.php;https://www.php.net/manual/en/ziparchive.close.php

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>