ZipStream-PHP 流式 ZIP 文件生成库使用指南-优快云博客

ZipStream-PHP 流式 ZIP 文件生成库使用指南

ZipStream-PHP :floppy_disk: PHP ZIP Streaming Library 项目地址: https://gitcode.com/gh_mirrors/zi/ZipStream-PHP

项目概述

ZipStream-PHP 是一个高效的 PHP 流式 ZIP 文件生成库，它允许开发者在不将 ZIP 文件写入磁盘的情况下，直接将 ZIP 内容流式传输给用户。这种处理方式特别适合处理大文件或大量文件，能显著减少内存占用和服务器磁盘 I/O 压力。

核心优势

内存高效：无需在服务器上生成完整的 ZIP 文件
即时传输：文件内容可以边生成边传输给客户端
支持多种数据源：字符串、本地文件、流资源、PSR7 流等
兼容性强：可与 S3 存储桶或任何 PSR7 流配合使用

安装方法

使用 Composer 进行安装：

composer require maennchen/zipstream-php

如果需要使用 PSR7 流相关功能，还需安装以下依赖：

composer require psr/http-message guzzlehttp/psr7

注意：如果系统缺少 mbstring 扩展，安装时会提示错误，可以通过以下命令解决：

composer require symfony/polyfill-mbstring

基础使用示例

require 'vendor/autoload.php';

// 初始化 ZipStream 对象
$zip = new ZipStream\ZipStream(
    outputName: 'example.zip',
    sendHttpHeaders: true, // 自动发送 HTTP 头
);

// 添加文本文件
$zip->addFile(
    fileName: 'hello.txt',
    data: '文件内容示例',
);

// 添加本地文件
$zip->addFileFromPath(
    fileName: 'photo.jpg',
    path: 'path/to/local/photo.jpg',
);

// 添加流资源文件
$tempFile = tmpfile();
fwrite($tempFile, '流式内容示例');
rewind($tempFile);
$zip->addFileFromStream(
    fileName: 'stream.txt',
    stream: $tempFile,
);
fclose($tempFile);

// 完成 ZIP 生成
$zip->finish();

高级功能

1. 自定义文件属性

可以为每个文件设置修改时间、注释等信息：

$zip->addFile(
    fileName: 'config.ini',
    data: $configContent,
    comment: '系统配置文件', // 文件注释
    lastModificationDateTime: new DateTime('2023-01-01'), // 修改时间
);

2. 处理大文件

对于大文件，建议使用流式添加而非直接加载到内存：

// 更高效的大文件处理方式
$zip->addFileFromPath(
    fileName: 'large_video.mp4',
    path: 'path/to/large_file.mp4',
);

3. 兼容性设置

针对不同系统的解压工具兼容性问题，可以调整 ZIP 格式：

$zip = new ZipStream\ZipStream(
    outputName: 'compatible.zip',
    enableZip64: false, // 禁用 Zip64 格式以提高兼容性
);

常见问题解决方案

macOS 解压问题：
- 现象：旧版 macOS 归档工具无法打开 ZIP 文件
- 解决方案：创建 ZIP 时设置 enableZip64: false
Linux unzip 乱码问题：
- 现象：unzip 工具处理 Unicode 文件名异常
- 解决方案：建议使用 7-zip 等现代解压工具
重复文件路径问题：
- 注意：库不会自动检测重复文件路径
- 建议：在添加文件前自行检查文件名唯一性