PHP PharData 怎样读取压缩包内的文件名

我在处理归档清单时，最容易混淆的不是 foreach，而是“当前条目到底是什么对象”。PHP 的 PharData 用来访问非可执行的 tar 或 zip 数据归档，遍历后得到的是文件信息对象；读取文件名时，直接调用 getFilename()，需要保留归档内层级时再看 getSubPathname()。

官方地址：https://www.php.net/manual/en/class.phardata.php

构造器说明：https://www.php.net/manual/en/phardata.construct.php

下面的示意图都由 ImageGen 生成，是静态结构说明图，不是浏览器、终端、编辑器或 PHP 运行截图。

先确认 PharData 的对象边界

PharData 继承了递归目录迭代器的能力。它负责打开归档并暴露条目，RecursiveIteratorIterator 负责把嵌套目录下的条目统一遍历出来，当前条目则可以按文件信息对象使用。把这三层职责分开后，读取文件名就不会误写成“先把压缩包解压到临时目录”。

这里的目标只是列出归档里的名字，不读取文件内容，也不讨论解压策略。PHP 官方手册把 PharData 定义为访问和创建非可执行 tar、zip 归档的高层接口；因此它正好适合做归档目录清单。

用 CURRENT_AS_FILEINFO 读取当前文件名

最小写法是给构造器传入 Phar::CURRENT_AS_FILEINFO，让迭代得到的当前值保持为文件信息对象。示例使用官方手册中常见的 Phar::KEY_AS_FILENAME，它影响键的形式；真正读取当前条目名称时，直接调用对象的 getFilename() 更直观。

getFilename() . PHP_EOL;
        }
    }
} catch (UnexpectedValueException $e) {
    // 归档不存在、格式不支持或无法打开时，给调用方明确错误
    throw new RuntimeException('无法打开数据归档', 0, $e);
}
?>

这个版本解决的是“怎么拿到当前条目的文件名”。如果只关心 basename，它已经够用；不要为了拿一个名称把每个条目都读成字符串内容。

需要目录层级时，读取归档内相对路径

当归档中同时存在 docs/readme.md 和 readme.md 时，只保存 getFilename() 会丢失目录信息。此时用递归迭代器遍历嵌套条目，并读取 getSubPathname()；它表达的是相对于归档根的子路径和文件名。

getFilename();
        // getSubPathname 适合保留 docs/readme.md 这一类层级信息
        $relativePath = $iterator->getSubPathname();
        printf("name=%s path=%s%s", $name, $relativePath, PHP_EOL);
    }
} catch (UnexpectedValueException $e) {
    // 打开阶段失败时不要把空列表误报成“归档没有条目”
    throw new RuntimeException('归档读取失败', 0, $e);
}
?>

文件名和相对路径是两个不同字段：前者适合展示，后者适合做去重、索引和后续定位。若业务只需要名字，可以只保留 getFilename()；若要在归档内唯一定位条目，应保留 getSubPathname()。

过滤目录，并保留条目判断

归档本身可能保存显式目录条目，也可能只出现文件。把所有当前对象都当成文件，会让目录名混进导入清单。读取时保留 isDir()，由业务决定是跳过目录，还是把目录也输出为一种条目类型。

isDir()) {
                continue;
            }

            $files[] = [
                'name' => $entry->getFilename(),
                'path' => $iterator->getSubPathname(),
                'is_dir' => false,
            ];
        }

        return $files;
    } catch (UnexpectedValueException|PharException $e) {
        // 让上层区分打开失败与“归档确实没有文件”
        throw new RuntimeException('无法列出归档文件', 0, $e);
    }
}
?>

这个函数的边界比较清楚：它只列出文件，不读取内容，也不负责解压。调用方拿到的 name 适合显示，path 适合保留归档内层级，异常则继续向上交给任务层处理。

最后检查三个容易踩坑的地方

如果只是一次性打印名称，第一段代码即可；如果要做归档索引，建议采用最后一个函数的返回结构。关键不是把 PharData 当成“解压工具”，而是把它当成一个可递归访问的归档条目迭代器。

常见问题

PharData 能读取普通 zip 和 tar 吗？

可以。PharData 面向非可执行的数据归档，官方手册列出的用途包括普通 tar 和 zip。本文只讨论读取条目名称，不涉及归档内容是否可信。

为什么不用数组下标直接取文件名？

数组访问更适合已知归档内路径的场景；需要遍历全部条目时，迭代器能同时提供文件信息、目录判断和层级路径，结构更清楚。

getFilename 和 getSubPathname 有什么区别？

getFilename() 返回当前条目的最后一段名称，getSubPathname() 保留相对于迭代根的子目录与文件名。前者适合展示，后者适合唯一定位。