PHP PharData::compressFiles 怎样批量压缩归档文件

如果目标是“把归档里的每个文件批量压缩”，先确认归档格式：PharData::compressFiles() 面向 ZIP 归档中的文件条目；对 TAR 调用它会抛出 BadMethodCallException。TAR 应改用 PharData::compress() 压缩整个归档。这个区别比压缩常量本身更重要。

官方文档地址：https://www.php.net/manual/en/phardata.compressfiles.php。下面只讨论 PHP 原生 PharData 的归档压缩，不展开上传和第三方归档库。

先分清 ZIP 条目和 TAR 整体

PharData 可以访问和创建非可执行的 tar、zip 归档，但两个格式的压缩边界不同。ZIP 可以让归档中的文件分别使用 Gzip 或 Bzip2；TAR 的文件格式不支持把每个条目单独压缩，因此只能把整个 tar 作为一个整体压成 .tar.gz 或 .tar.bz2。

可以把选择记成一张小表：

ZIP 归档怎样批量压缩文件

对 ZIP 数据归档，调用 compressFiles() 并传入 Phar::GZ 或 Phar::BZ2。传入 Phar::NONE 则表示移除条目压缩。函数返回 void，所以不要把返回值当成新的归档对象。

compressFiles(Phar::GZ);

// 如需取消条目压缩，可改用 Phar::NONE；不要同时重复调用不同策略。
// $archive->compressFiles(Phar::NONE);

如果 ZIP 中已经有使用 Bzip2 或 Gzip 压缩的文件，重新压缩前需要对应扩展先解压这些条目；文档也明确要求启用 zlib 或 bzip2 才能使用相应能力。不要把“方法执行成功”误解成“所有条目都变小”，已经压缩过的内容可能几乎没有收益。

TAR 归档为什么要改用 compress

TAR 不能使用 compressFiles() 做条目级压缩。若输入是 reports.tar，应该压缩整个归档：

compress(Phar::GZ);
if ($compressed === null) {
    throw new RuntimeException('TAR 整体压缩没有返回归档对象');
}

// 需要 Bzip2 时改用 Phar::BZ2，并确认 bzip2 扩展已启用。
// $compressed = $tar->compress(Phar::BZ2);

compress() 的参数仍然是 Phar::GZ、Phar::BZ2 或 Phar::NONE，但语义是整个 tar/zip 归档的压缩。对 TAR，官方文档说明默认扩展名分别是 .tar.gz 和 .tar.bz2；第二个参数还可以显式指定扩展名。

把前置条件和异常边界写进程序

压缩操作会改写归档内容或创建压缩副本，部署环境需要关注 phar.readonly、zlib 和 bzip2。官方文档列出的失败条件包括只读配置开启、缺少所需扩展，以及已有条目使用了当前环境无法解压的压缩方式。TAR 调用 compressFiles() 还会直接落入格式不支持的异常分支。

compressFiles(Phar::GZ);
} catch (BadMethodCallException $e) {
    // 记录格式、INI 配置和扩展状态，避免只保留“压缩失败”四个字。
    error_log('PharData 压缩条件不满足：' . $e->getMessage());
    throw $e;
}

• ZIP 条目压缩：选择 compressFiles()，并确保对应压缩扩展可用。
• TAR 整体压缩：选择 compress()，不要尝试逐个条目压缩。
• 取消压缩：使用 Phar::NONE，但仍要考虑生成文件和已有目标文件的处理。
• 异常排查：同时记录归档格式、phar.readonly 和 zlib/bzip2 状态。

常见问题

为什么 TAR 调用 compressFiles 会报错？因为 TAR 文件格式不支持条目级压缩；改用 compress(Phar::GZ) 或 compress(Phar::BZ2) 压缩整个归档。

compressFiles 会返回新的 PharData 吗？不会，它的返回类型是 void；需要拿到压缩后的归档对象时，应看 compress() 的返回值。