PHP PharData 怎样向 TAR 归档追加文件

PharData 适合处理普通的、非可执行的 TAR 或 ZIP 数据归档。向 TAR 追加磁盘文件时，先用归档文件路径创建 PharData，再调用 addFile($filename, $localName)；如果内容是在程序里生成的，则使用 addFromString($localName, $contents)。第二个参数决定文件在归档内的路径，不等于服务器磁盘路径。

本文只讨论 TAR 数据归档的追加写入，不把它当作可执行 Phar，也不展开签名和压缩格式转换。官方地址：https://www.php.net/

最小写法是 $tar = new PharData('/绝对路径/archive.tar');，然后把外部文件交给 addFile()，把内存内容交给 addFromString()。文件数量较多时，不要在循环里盲目逐次追加，应改用批量构建入口。

先区分 PharData、TAR 与可执行 Phar

PharData 的定位是访问和创建非可执行的 TAR、ZIP 归档。普通 TAR 没有可执行 Phar 所需的 stub，因此不要把 PharData 与 new Phar('app.phar') 混为一谈。本文的目标是生成一个可以交给归档工具读取的 archive.tar，不是打包一个可直接执行的 PHP 应用。

构造函数接收已有归档或待创建归档的文件名。生产代码建议传入确定的绝对路径，并在外层捕获打开失败、格式不兼容和写入失败；不要把用户输入未经限制地拼接为任意文件路径。

用 addFile 映射磁盘文件到归档路径

addFile() 的第一个参数是 PHP 进程能读取的磁盘文件或可访问资源，第二个参数是归档内部的相对路径。显式填写内部路径可以避免把服务器目录结构泄露给归档使用者，也能让解压后的目录布局保持稳定。

addFile($sourcePath, 'reports/report.json');
} catch (Throwable $e) {
    // 记录真实异常，调用方再决定是否重试或返回业务错误。
    throw new RuntimeException('追加文件到 TAR 失败：' . $e->getMessage(), 0, $e);
}

这里的 reports/report.json 是归档内路径。读取归档时可以通过同样的内部路径定位文件；它不应该随着部署目录变化。addFile() 没有返回一个“写入成功的布尔值”，失败时应按异常处理。

用 addFromString 写入生成内容

如果文件内容来自序列化、模板渲染或接口结果，不必先落地临时文件，可以直接调用 addFromString()。它的第一个参数同样是归档内路径，第二个参数是要写入的字符串。

 'tar',
    'files' => ['reports/report.json'],
];

try {
    // 数组转成字符串后直接放进归档，不需要中间临时文件。
    $tar = new PharData($archivePath);
    $json = json_encode($manifest, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
    $tar->addFromString('manifest.json', $json);
} catch (Throwable $e) {
    // JSON 编码或归档写入任一环节失败，都让任务明确失败。
    throw new RuntimeException('写入 manifest.json 失败：' . $e->getMessage(), 0, $e);
}

同一归档内的路径要提前规划，例如把机器生成的清单放在根目录，把业务文件放入 reports/。如果目标路径已经存在，不要假设调用会自动合并版本；对覆盖、跳过还是改名，应由业务规则先做决定。

重复路径、异常与逐次写回怎么处理

追加操作面对的不是一个抽象数组，而是实际归档文件。路径重复、源文件不可读、归档格式损坏或目标目录没有写权限，都可能在保存阶段抛出异常。应用层要保留归档路径和原始异常上下文，避免只返回“打包失败”这种无法定位的提示。

官方文档特别指出，addFile()、addFromString() 和数组式的 offsetSet() 每次调用都会保存新的归档。也就是说，下面这样的循环在文件很多时会产生多次写回：

 __DIR__ . '/build/a.txt', 'name' => 'data/a.txt'],
    ['source' => __DIR__ . '/build/b.txt', 'name' => 'data/b.txt'],
];

foreach ($entries as $entry) {
    // 每次调用都会触发一次归档写回，适合少量追加而非大批量导入。
    $tar->addFile($entry['source'], $entry['name']);
}

少量、低频的增量文件可以这样写；批量任务则应把输入收集好后一次构建。若中途发生异常，保留失败任务的日志和目标文件状态，不要把残留的归档直接当成完整产物。

根据文件数量选择批量构建

当任务是“把一个目录中的一组文件打成 TAR”，优先考虑 buildFromDirectory()；如果已经有自定义迭代器、筛选逻辑或稳定的内部路径映射，则考虑 buildFromIterator()。这两个入口更适合集中构建，避免循环里逐次调用追加方法。

buildFromDirectory($sourceDir, '/\.json$/');

// 返回映射可用于记录内部路径与源文件的对应关系。
if (!is_array($added)) {
    throw new RuntimeException('批量构建没有返回文件映射');
}

批量构建并不意味着可以忽略错误。目录扫描规则、排除规则和目标路径仍要经过业务设计，构建失败时也要把异常传回任务调度器。文章中的图只表达方法之间的关系，不代表某次真实执行的耗时或文件数量。

检查 TAR 格式与部署约束

TAR 归档的文件名包含路径长度等格式约束，PHP 官方的 TAR 文档还说明了 USTAR、PAX 和 GNU Tar 兼容范围。若归档要交给外部系统消费，应先约定它支持的 TAR 变体和压缩方式；不要把“能由 PharData 打开”直接推断成“所有归档工具都完全兼容”。

另外，PharData 处理的是数据归档，不需要为 TAR 设置可执行 stub。部署时应确认 PHP 的 Phar 扩展可用、运行用户有目标目录写权限，并把归档输出写到临时文件后再按业务规则完成交付，避免读者在并发场景下拿到尚未完成的产物。

PharData 能不能直接生成可执行 Phar？

当前文章中的 PharData 面向非可执行 TAR/ZIP。可执行 Phar 需要另一套对象和 stub 语义，不能把普通 TAR 追加流程当成应用打包流程。

为什么 addFile 的第二个参数不能写服务器绝对路径？

第二个参数是归档内路径。写入服务器绝对路径会让归档结构失去可移植性，甚至泄露部署目录；应使用稳定的相对路径。

很多文件时还要逐个调用 addFile 吗？

少量增量文件可以逐个调用；大量文件优先收集输入并使用批量构建方法，减少逐次保存带来的开销。

参考：PharData 官方手册、PharData::addFile、PharData::addFromString、PharData::buildFromDirectory、TAR-based phars。