README

PHP 原生 ZipArchive 的简单包装，使得操作更加方便。

安装

使用 Composer 将此包作为依赖项安装。

composer require glucnac/ziparchivemanager

使用方法

GlucNAc/ZipArchiveManager 提供了一个更面向对象的接口，用于处理 PHP 原生的 ZipArchive，使得创建、提取和修改 zip 归档更加容易。

创建新的 ZipArchive

要创建一个新的 zip 归档，您可以使用 ZipArchiveBuilder 类。该类需要一个 ZipArchiveManager 对象来管理归档的存储。该类提供了一个流畅的接口，用于向归档中添加文件。

use GlucNAc\ZipArchiveManager\ZipArchiveBuilder;
use GlucNAc\ZipArchiveManager\ZipArchiveManager;

$zipArchiveManager = new ZipArchiveManager('/path/to/storage/archive');
$zipArchiveBuilder = new ZipArchiveBuilder($zipArchiveManager);

$zipArchive = $zipArchiveBuilder
    ->new('test.zip')
    ->addFiles([
        '/path/to/file1.txt',
        '/path/to/dir/file2.txt',
    ])
    ->addFile('/path/to/file3.txt')
    ->build();

现在归档已存在于 /path/to/storage/archive/test.zip，并将具有以下结构

test.zip
├── /path/to/file1.txt
├── /path/to/file3.txt
└── /path/to/dir
             └── file2.txt

这也可以通过 ZipArchiveBuilder::buildWithFiles 方法快速完成

use GlucNAc\ZipArchiveManager\ZipArchiveManager;
use GlucNAc\ZipArchiveManager\ZipArchiveBuilder;

$zipArchiveManager = new ZipArchiveManager('/path/to/storage/archive');
$zipArchiveBuilder = new ZipArchiveBuilder($zipArchiveManager);

$zipArchive = $zipArchiveBuilder->buildWithFiles('test.zip', [
    '/path/to/file1.txt',
    '/path/to/dir/file2.txt',
    '/path/to/file3.txt',
]);

自定义归档中的文件结构

默认情况下，归档结构将反映文件的目录结构。如果您想更改归档中文件的目录结构，可以使用一个关联数组，键是文件的路径，值是归档中文件的路径。

use GlucNAc\ZipArchiveManager\ZipArchiveManager;
use GlucNAc\ZipArchiveManager\ZipArchiveBuilder;

$zipArchiveManager = new ZipArchiveManager('/path/to/storage/archive');
$zipArchiveBuilder = new ZipArchiveBuilder($zipArchiveManager);

$zipArchive = $zipArchiveBuilder->buildWithFiles('test.zip', [
    '/path/to/file1.txt' => 'file1.txt',
    '/path/to/dir/file2.txt' => 'dir/file2.txt',
    '/path/to/file3.txt' => 'file3.txt',
]);

现在归档已存在于 /path/to/storage/archive/test.zip，并将具有以下结构

test.zip
├── file1.txt
├── file3.txt
└── dir
    └── file2.txt

从目录添加文件

给定以下目录结构

/path/to
├── file1.txt
├── file3.txt
└── dir
    └── file2.txt

如果您想创建一个包含 /path/to 目录中所有文件的归档，同时保持归档中文件的目录结构，可以使用 ZipArchiveBuilder::addFilesFromPath 方法。

use GlucNAc\ZipArchiveManager\ZipArchiveBuilder;
use GlucNAc\ZipArchiveManager\ZipArchiveManager;

$zipArchiveManager = new ZipArchiveManager('/path/to/storage/archive');
$zipArchiveBuilder = new ZipArchiveBuilder($zipArchiveManager);

$zipArchive = $zipArchiveBuilder->buildWithFiles(
    'test.zip',
    ArchivableFileManager::getArchivableFilesFromPath('/path/to'),
);

ArchivableFileManager::getArchivableFilesFromPath 方法返回一个 ArchivableFile 对象数组，这些对象实现了 ArchivableFileInterface 接口，其中归档中文件的路径将相对于传递给方法的路经（在此例中为 /path/to）。

这之所以有效，是因为 ZipArchiveBuilder::buildWithFiles、ZipArchiveBuilder::addFiles 和 ZipArchiveBuilder::addFile 方法也接受 ArchivableFileInterface 对象数组（除了文件路径）。

有关 ArchivableFileInterface 和 ArchivableFile 对象的更多信息，请参阅 ArchivableFile 部分。

保持归档打开

默认情况下，build 方法在构建归档后会关闭它。如果您想保持归档打开，可以将 false 作为第一个参数传递给 build 方法。

use GlucNAc\ZipArchiveManager\ZipArchiveManager;
use GlucNAc\ZipArchiveManager\ZipArchiveBuilder;

$zipArchiveManager = new ZipArchiveManager('/path/to/storage/archive');
$zipArchiveBuilder = new ZipArchiveBuilder($zipArchiveManager);

$zipArchive = $zipArchiveBuilder
    ->new('test.zip')
    ->addFiles([
        '/path/to/file1.txt',
        '/path/to/dir/file2.txt',
    ])
    ->addFile('/path/to/file3.txt')
    ->build(false);

// Do something with the archive

// Close the archive: this will save the archive to the storage
$zipArchiveManager->close($zipArchive);

向现有的 zip 归档添加文件

要向现有的 zip 归档添加文件，只需使用 ZipArchiveManager::open 方法打开归档，并使用 创建新的 ZipArchive 部分中描述的方法。

use GlucNAc\ZipArchiveManager\ZipArchiveManager;

$zipArchiveManager = new ZipArchiveManager('/path/to/storage/archive');

// Assume the archive exists at /path/to/storage/archive/test.zip
$zipArchive = $zipArchiveManager->open('test.zip');

从 ZipArchive 中提取文件

要从 zip 归档中提取文件，请简单使用 ZipArchiveManager::extractFiles 方法。

use GlucNAc\ZipArchiveManager\ZipArchiveManager;

$zipArchiveManager = new ZipArchiveManager('/path/to/storage/archive');

// Assume the archive exists at /path/to/storage/archive/test.zip
$zipArchive = $zipArchiveManager->open('test.zip');

$zipArchiveManager->extractFiles($zipArchive, '/path/to/extracted/files/dir');

ArchivableFile

对于本节，让我们考虑以下目录结构

/path/to
├── file1.txt
├── file3.txt
└── dir
    └── file2.txt

你可能已经注意到，ZipArchiveManager 使用 ArchivableFile 类来表示可以添加到 zip 归档中的文件。更确切地说，ZipArchiveManager 期望一个实现了 ArchivableFileInterface 接口的对象。该接口定义了对象必须实现的方法，以便被认为是可归档文件。本包提供的 ArchivableFile 类实现了此接口，并提供了一种简单的方式来处理可以添加到 zip 归档中的文件。

interface ArchivableFileInterface
{
    public function getFullPath(): string;
    public function getFileName(): string;
    public function getExtension(): string;

    /**
     * This method is used to get the name of the file inside the archive. It can be useful to rename
     * the file on the fly, or to put it in a subdirectory by returning a relative path.
     */
    public function getEntryName(): string;
    public function setEntryName(string|null $entryName): static;
}

$archivableFile = new ArchivableFile('/path/to/file1.txt');

$archivableFile->getFullPath();  // /path/to/file1.txt
$archivableFile->getFileName();  // file1.txt
$archivableFile->getExtension(); // txt
$archivableFile->getEntryName(); // /path/to/file1.txt (by default, the entry name equals the full path)

你可以创建自己的类来实现此接口，或者可以使用本包提供的 ArchivableFile 类。为此，你可以使用 ArchivableFileManager::getArchivableFileFromPath 方法从一个文件路径获取 ArchivableFile 对象。

use GlucNAc\ZipArchiveManager\ArchivableFileManager;

$archivableFile = ArchivableFileManager::getArchivableFileFromPath('/path/to/file1.txt');
$archivableFile->setEntryName('file1.txt'); // This will be the path of the file in the archive

你也可以使用 ArchivableFileManager::getArchivableFilesFromPath 方法从一个目录路径获取一个 ArchivableFile 对象的数组。

use GlucNAc\ZipArchiveManager\ArchivableFileManager;

[$file1, $file2, $file3] = ArchivableFileManager::getArchivableFilesFromPath('/path/to');

// By default, when using the ArchivableFileManager::getArchivableFilesFromPath method,
// the entry name of the files will be relative to the path passed to the method.
$file1->getEntryName(); // file1.txt
$file2->getEntryName(); // dir/file2.txt
$file3->getEntryName(); // file3.txt

内部，ArchivableFile 类使用 SplFileInfo 类来表示文件。你也可以使用 SplFileInfoToArchivableFileTransformer 类将一个 SplFileInfo 对象转换为 ArchivableFile 对象。

use GlucNAc\ZipArchiveManager\ArchivableFile;

$splFileInfo = new SplFileInfo('/path/to/file.txt');

$archivableFile = SplFileInfoToArchivableFileTransformer::getArchivableFile($splFileInfo);

贡献

欢迎贡献！要贡献，请熟悉 CONTRIBUTING.md。

协调披露

保护用户信息的安全和保密是我们的首要任务，我们欢迎外部安全研究者的贡献。如果你认为你在本存储库维护的软件中找到了安全漏洞，请阅读 SECURITY.md 以了解提交漏洞报告的说明。

版权和许可

GlucNAc/ZipArchiveManager 版权所有 © GlucNAc，并根据 MIT 许可证（MIT）许可使用。有关更多信息，请参阅 LICENSE。