TP5自定义压缩函数需封装ZipArchive类，必须显式new \ZipArchive()、检查open返回值、addFile时避免绝对路径、调用close()，且common.php中须用全限定类名。
TP5 自定义函数写压缩逻辑，核心是封装 ZipArchive 操作，不能直接用 zip() 这种裸函数名——它既不是 PHP 内置函数，也不在 TP5 命名空间里，硬写会报 Call to undefined function zip()。
自定义压缩函数必须基于 ZipArchive 类
TP5 本身不提供压缩工具类，得靠 PHP 原生 ZipArchive（需确认已启用 php_zip.dll 或 extension=zip）。你写的函数本质是封装它的打开、添加、关闭三步，不能跳过实例化。
- 函数必须显式
new \ZipArchive()，不能省略反斜杠（否则可能被当成当前命名空间下的类） - 必须检查
$zip->open()返回值，ZIPARCHIVE::CREATE失败时返回错误码（如19表示路径不可写） - 添加文件用
$zip->addFile($realPath, $archiveName)，第二个参数决定压缩包内路径，别直接传原始绝对路径（否则解压出来是C:/xxx/xxx.txt） - 最后必须调用
$zip->close()，否则生成的 zip 损坏，Windows 下提示“压缩包无效”
application/common.php 中定义函数要带命名空间兼容性
TP5 的 common.php 是纯函数文件，不支持 use 导入类，所以所有类名必须全限定。别写 use ZipArchive;，那是无效的。
function zipFiles(array $files, string $zipPath): bool
{
$zip = new \ZipArchive();
$res = $zip->open($zipPath, \ZipArchive::CREATE);
if ($res !== true) {
return false;
}
foreach ($files as $file) {
if (is_file($file)) {
// 提取文件名，避免绝对路径污染压缩包结构
$basename = basename($file);
$zip->addFile($file, $basename);
}
}
$zip->close();
return is_file($zipPath) && filesize($zipPath) > 0;
}
- 参数类型声明（
array、string）能提前拦截误传，TP5.1+ 支持，建议加上 - 返回
bool而非资源或数组，符合 TP5 公共函数惯例（如input()、config()都倾向布尔或具体值） - 没做递归目录打包——那是另一个函数的事，这个函数只处理明确传入的文件列表
控制器里调用前必须确保路径真实存在且可写
常见错误不是代码写错，而是 $zipPath 指向一个不存在的目录，比如 ../runtime/zip/test.zip，但 runtime/zip/ 目录根本没创建。
- 用
dirname($zipPath)+is_dir()+mkdir(..., 0755, true)预检并创建父目录 - 不要用相对路径如
uploads/test.zip，TP5 CLI 和 Web 请求的工作目录不同，优先用ROOT_PATH . 'public/uploads/test.zip' - 上传后立即压缩？先
move()到临时目录，再传给zipFiles()，别试图边上传边塞进 zip - 压缩失败时，
$zip->getStatusString()在 PHP 8.0+ 才有，低版本只能靠错误码查表，建议记录$res值到日志
模板里不能直接调用压缩函数
别在 {:zipFiles(...)} 里调用——模板引擎不执行函数副作用，且 zipFiles() 是写文件操作，放模板里违反 MVC 分离原则，还会导致多次请求重复压缩。
- 压缩必须放在控制器或服务类中，完成后返回压缩包 URL 或状态
- 模板只负责展示链接或按钮，点击触发下载（用
return download($zipPath)） - 如果想“前台点一下就打包下载”，后端接口应生成唯一 zip 名（如含时间戳），压缩完立刻返回
readfile()+header()，而不是让模板去调函数
真正容易被忽略的是：压缩函数一旦写进 common.php，它就在所有请求生命周期里全局可用，但 ZipArchive 实例不是线程安全的。如果你在并发场景下（比如多个用户同时触发打包），别复用同一个 $zip 实例，每次调用都必须 new 一个新的。
