kiwilan/php-archive

PHP package to handle archives (.zip, .rar, .tar, .7z) or .pdf with hybrid solution (native/p7zip), designed to works with eBooks (.epub, .cbz, .cbr, .cb7, .cbt).

1.2.01 2023-05-05 06:30 UTC

Requires

• php: ^8.1
• smalot/pdfparser: ^2.4
• symfony/process: ^6.2

Requires (Dev)

• laravel/pint: ^1.6
• pestphp/pest: ^2.0
• phpstan/phpstan: ^1.10
• spatie/ray: ^1.28

Suggests

• ext-imagick: *
• ext-rar: *

MIT

• Ewilan Rivière

• php
• pdf
• ebook
• zip
• epub
• archive
• tar
• 7z
• rar
• 7zip
• cbr
• cbt
• cbz
• cb7

README

PHP package to handle archives (.zip, .rar, .tar, .7z) or .pdf with hybrid solution (native/p7zip), designed to works with eBooks (.epub, .cbz, .cbr, .cb7, .cbt).

Supports Linux, macOS and Windows.

Warning

For some formats (.rar and .7z) rar PHP extension or p7zip binary could be necessary, see Requirements.

Requirements

• PHP >= 8.1
• Depends of archive type and features you want to use

Type	Native	Dependency
.zip, .epub, .cbz	✅	N/A
.tar, .tar.gz, .cbt	✅	N/A
.rar, .cbr	❌	rar PHP extension or p7zip binary
.7z, .cb7	❌	p7zip binary
.pdf	✅	Optional (for extraction) imagick PHP extension
ALL	❌	p7zip binary (rar PHP extension and imagick PHP extension are optional)

Note

Here you can read some installation guides for dependencies

• p7zip guide
• rar PHP extension guide
• imagick PHP extension guide

Warning

• On macOS, for .rar extract, you have to install rar binary to extract files, p7zip not support .rar extraction.
• On Windows, for .pdf extract, imagick PHP extension have to work but my tests failed on this feature. So to extract PDF pages I advice to use WSL.

If you want more informations, you can read section About.

Features

• List files as ArchiveItem array
  • With files method: list of files
  • With first method: first file
  • With last method: last file
  • With find method: find first file that match with path property
  • With filter method: find all files that match with path property
• Content of file
  • With content method: content of file as string (useful for images)
  • With text method: content of text file (binaries files return null)
• Extract files
  • With extract method: extract files to directory
  • With extractAll method: extract all files to directory
• Metadata of archive with title, author, subject, creator, creationDate, modDate, status and comment properties
  • Useful for PDF files
• Count files
• Create or edit archives, only with .zip format
  • With make method: create or edit archive
  • With addFiles method: add files to archive
  • With addFromString method: add string to archive
  • With addDirectory and addDirectories methods: add directories to archive
  • With save method: save archive

Installation

You can install the package via composer:

composer require kiwilan/php-archive

Usage

Read and extract

With archive file (.zip, .rar, .tar, .7z, epub, cbz, cbr, cb7, cbt, tar.gz, .pdf).

$archive = Archive::test('path/to/archive.zip');

$files = $archive->files(); // ArchiveItem[]
$count = $archive->count(); // int of files count

$images = $archive->filter('jpeg'); // ArchiveItem[] with `jpeg` in their path
$metadataXml = $archive->find('metadata.xml'); // First ArchiveItem with `metadata.xml` in their path
$content = $archive->content($metadataXml); // `metadata.xml` file content

$paths = $archive->extract('/path/to/directory', [$metadataXml]); // string[] of extracted files paths
$paths = $archive->extractAll('/path/to/directory'); // string[] of extracted files paths

PDF files works with same API than archives but with some differences.

$archive = Archive::test('path/to/file.pdf');

$metadata = $archive->metadata(); // Metadata of PDF

$content = $archive->content($archive->first()); // PDF page as image
$text = $archive->text($archive->first()); // PDF page as text

Create

You can create archive with method Archive::make method.

Works only with .zip archives.

$archive = Archive::make('path/to/archive.zip');
$archive->addFiles([
    'path/to/file1.txt',
    'path/to/file2.txt',
    'path/to/file3.txt',
]);
$archive->addFromString('test.txt', 'Hello World!');
$archive->addDirectory('path/to/directory');
$archive->save();

Edit

You can edit archive with same method Archive::make method.

$archive = Archive::make('path/to/archive.zip');
$archive->addFromString('test.txt', 'Hello World!');
$archive->save();

Testing

composer test

About

This package was inspired by this excellent post on StackOverflow which make state of the art of PHP archive handling. The package Gemorroj/Archive7z was also a good source of inspiration cause it's the only package that handle .7z archives with wrapper of p7zip fork binary. But I would to handle all main archives formats with native PHP solution it possible, and use p7zip binary only if native solution is not available.

State of the art of PHP archive handling:

• .zip with ZipArchive
• .tar with PharData
• .rar with RarArchive if rar extension is installed
• .7z can't be handled with native PHP solution

Type	Is native	Solution
ZIP	✅	Native
TAR	✅	Native
RAR	❌	rar or p7zip binary
7ZIP	❌	p7zip binary
PDF	❌	smalot/pdfparser

Why not full wrapper of p7zip binary?

This solution is used by Gemorroj/Archive7z, and it works well. But another problem is the usage of the p7zip fork which is not the official p7zip binary and can be difficult to install on some systems.

PHP can handle natively some archive formats, but not all. So I choose to use native PHP solution when it's possible, and use p7zip binary with official version when it's not possible.

Case of rar

The rar PHP extension is not installed by default on PHP, developers have to install it manually. This extension is not actively maintained and users could have some compilation problems. To install it with PHP 8.1 or 8.2, it's necessary to compile manually the extension, you could read this guide if you want to install it (for PHP 8.2, you will have a warning message but it's not a problem, the extension will work).

But rar PHP extension is a problem because it's not sure to have a compatibility with future PHP versions. So I choose to handle rar archives with p7zip binary if rar PHP extension is not installed.

Case of 7zip

PHP can't handle .7z archives natively, so I choose to use p7zip binary. You will have to install it on your system to use this package. You could read this guide if you want to install it.

Case of pdf

PHP can't handle .pdf archives natively, so I choose to use smalot/pdfparser package, embedded in this package. To extract pages as images, you have to install imagick extension you could read this guide if you want to install it.

eBooks and comics

This package can handle .epub, .cbz, .cbr, .cb7, .cbt archives, it's depends of the extension, check requirements section.

More

Alternatives:

• Gemorroj/Archive7z: handle many archives with p7zip-project/p7zip binary
• splitbrain/php-archive: native PHP solution to handle .zip and .tar archives

Documentation:

• List files in .7z, .rar and .tar archives using PHP: https://stackoverflow.com/a/39163620/11008206
• Compression and Archive Extensions: https://www.php.net/manual/en/refs.compression.php

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Kiwilan
• All Contributors
• spatie for spatie/package-skeleton-php
• smalot/pdfparser for PDF parser
• 7-zip for p7zip binary

License

The MIT License (MIT). Please see License File for more information.