imponeer / archive-download-builder
A PHP library for building and downloading archive files (ZIP and TAR.GZ) with optional Flysystem support for various file sources
Requires
- php: ^8.3
- httpsoft/http-emitter: ^1.1
- league/flysystem: ^3.0
- nelexa/zip: ^4.0
- nyholm/psr7: ^1.8
- pear/archive_tar: ^1.6
Requires (Dev)
- league/flysystem-memory: ^3.29
- phpstan/phpstan: ^2.0
- phpunit/phpunit: ^12
- squizlabs/php_codesniffer: ^3.7
README
A PHP library for building and downloading archive files (ZIP and TAR.GZ) with support for various file sources through the Flysystem abstraction layer.
This library is a modern rewrite of the XOOPS downloader classes (Downloader, ZipDownloader, TarDownloader) with MIT license compatibility and modern PHP coding standards.
Installation
Install via Composer:
composer require imponeer/archive-download-builder
Examples
Simple ZIP Archive (using default filesystem)
<?php use Imponeer\ArchiveDownloadBuilder\ZipDownloader; // Create ZIP downloader (uses entire filesystem as base when no filesystem is specified) $downloader = new ZipDownloader(); // Add files from anywhere on the filesystem $downloader->addFile('/path/to/document.pdf'); $downloader->addFile('/home/user/image.jpg', 'renamed-image.jpg'); // Add file data directly $downloader->addFileData('Hello World!', 'hello.txt'); // Generate and download $downloader->download('my-archive');
ZIP Archive with Custom Filesystem
<?php use Imponeer\ArchiveDownloadBuilder\ZipDownloader; use League\Flysystem\Filesystem; use League\Flysystem\Local\LocalFilesystemAdapter; // Create filesystem adapter for a specific directory $filesystem = new Filesystem(new LocalFilesystemAdapter('/path/to/files')); // Create ZIP downloader with custom filesystem $downloader = new ZipDownloader(filesystem: $filesystem); // Add files to archive (paths are relative to the filesystem adapter) $downloader->addFile('document.pdf'); $downloader->addFile('image.jpg', 'renamed-image.jpg'); // Add file data directly $downloader->addFileData('Hello World!', 'hello.txt'); // Generate and download $downloader->download('my-archive');
Basic TAR.GZ Archive
<?php use Imponeer\ArchiveDownloadBuilder\TarDownloader; use League\Flysystem\Filesystem; use League\Flysystem\Local\LocalFilesystemAdapter; // Create filesystem adapter $filesystem = new Filesystem(new LocalFilesystemAdapter('/path/to/files')); // Create TAR downloader $downloader = new TarDownloader(filesystem: $filesystem); // Add files to archive $downloader->addFile('config.json'); $downloader->addBinaryFile('data.bin', 'backup-data.bin'); // Generate and download $downloader->download('backup');
Custom MIME Types and Extensions
// Custom ZIP configuration $zipDownloader = new ZipDownloader( ext: '.custom.zip', mimetype: 'application/custom-zip', filesystem: $filesystem ); // Custom TAR configuration $tarDownloader = new TarDownloader( ext: '.backup.tar.gz', mimetype: 'application/x-compressed-tar', filesystem: $filesystem, tmpPath: '/custom/temp/path' );
Working with Different Filesystems
use League\Flysystem\Filesystem; use League\Flysystem\InMemory\InMemoryFilesystemAdapter; use League\Flysystem\Ftp\FtpAdapter; use League\Flysystem\AwsS3V3\AwsS3V3Adapter; // In-memory filesystem $memoryFs = new Filesystem(new InMemoryFilesystemAdapter()); $downloader = new ZipDownloader(filesystem: $memoryFs); // FTP filesystem $ftpFs = new Filesystem(new FtpAdapter($ftpConfig)); $downloader = new ZipDownloader(filesystem: $ftpFs); // AWS S3 filesystem $s3Fs = new Filesystem(new AwsS3V3Adapter($s3Client, $bucket)); $downloader = new ZipDownloader(filesystem: $s3Fs);
PSR-7 Response Integration
// Get PSR-7 response instead of direct download $response = $downloader->toResponse('archive-name'); // Use with your favorite HTTP framework // Symfony return new Response($response->getBody(), $response->getStatusCode(), $response->getHeaders()); // Laravel return response($response->getBody(), $response->getStatusCode(), $response->getHeaders()); // Slim Framework return $response; // Direct usage
Bulk File Operations
use League\Flysystem\FileAttributes; // Add all files from a directory foreach ($filesystem->listContents('/documents', true) as $item) { if ($item instanceof FileAttributes) { $downloader->addFile($item->path()); } } // Add files with custom naming pattern $files = ['report1.pdf', 'report2.pdf', 'summary.doc']; foreach ($files as $index => $file) { $downloader->addFile($file, sprintf('report_%02d_%s', $index + 1, basename($file))); }
Error Handling
use PhpZip\Exception\ZipException; use League\Flysystem\FilesystemException; try { $downloader = new ZipDownloader(filesystem: $filesystem); $downloader->addFile('nonexistent-file.txt'); $downloader->download('archive'); } catch (FilesystemException $e) { // Handle filesystem errors (file not found, permission issues, etc.) echo "Filesystem error: " . $e->getMessage(); } catch (ZipException $e) { // Handle ZIP-specific errors echo "ZIP error: " . $e->getMessage(); }
Documentation
API documentation is automatically generated and available in the project's wiki. For more detailed information about the classes and methods, please refer to the project wiki.
Development
Running Tests
composer test
Code Quality
# PHP CodeSniffer composer phpcs # Fix coding standards composer phpcbf # Static analysis composer phpstan
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
Please ensure your code follows PSR-12 standards and includes appropriate tests.
Support
For issues and questions, please use the GitHub Issues page.