{"id":22547063,"url":"https://github.com/kiwilan/php-archive","last_synced_at":"2025-10-05T02:43:05.824Z","repository":{"id":147014217,"uuid":"616477528","full_name":"kiwilan/php-archive","owner":"kiwilan","description":"PHP package to handle archives (.zip, .rar, .tar, .7z, .pdf) with unified API and hybrid solution (native/p7zip), designed to works with EPUB and CBA (.cbz, .cbr, .cb7, .cbt).","archived":false,"fork":false,"pushed_at":"2025-02-03T17:12:31.000Z","size":3264,"stargazers_count":8,"open_issues_count":3,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-10T00:52:59.071Z","etag":null,"topics":["7z","7zip","archive","cb7","cba","cbr","cbt","cbz","ebook","epub","pdf","php","rar","tar","zip"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kiwilan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"kiwilan"}},"created_at":"2023-03-20T13:18:12.000Z","updated_at":"2025-04-03T14:22:40.000Z","dependencies_parsed_at":"2024-03-07T09:45:06.821Z","dependency_job_id":"f65010ee-fa11-4ae0-a1c6-ac65dea314db","html_url":"https://github.com/kiwilan/php-archive","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":"spatie/package-skeleton-php","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwilan%2Fphp-archive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwilan%2Fphp-archive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwilan%2Fphp-archive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwilan%2Fphp-archive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiwilan","download_url":"https://codeload.github.com/kiwilan/php-archive/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137995,"owners_count":21053775,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["7z","7zip","archive","cb7","cba","cbr","cbt","cbz","ebook","epub","pdf","php","rar","tar","zip"],"created_at":"2024-12-07T15:09:58.566Z","updated_at":"2025-10-05T02:43:00.783Z","avatar_url":"https://github.com/kiwilan.png","language":"PHP","funding_links":["https://github.com/sponsors/kiwilan"],"categories":[],"sub_categories":[],"readme":"# PHP Archive\n\n![Banner with archives picture in background and PHP Archive title](https://raw.githubusercontent.com/kiwilan/php-archive/main/docs/banner.jpg)\n\n[![php][php-version-src]][php-version-href]\n[![version][version-src]][version-href]\n[![downloads][downloads-src]][downloads-href]\n[![license][license-src]][license-href]\n[![tests][tests-src]][tests-href]\n[![codecov][codecov-src]][codecov-href]\n\nPHP package to handle archives (`.zip`, `.rar`, `.tar`, `.7z`, `.pdf`) with unified API and hybrid solution (native/`p7zip`), designed to works with EPUB and CBA (`.cbz`, `.cbr`, `.cb7`, `.cbt`).\n\nSupports Linux, macOS and Windows.\n\n\u003e [!WARNING]\n\u003e\n\u003e For some formats (`.rar` and `.7z`) [`rar` PHP extension](https://github.com/cataphract/php-rar) or [p7zip](https://www.7-zip.org/) binary could be necessary, see [Requirements](#requirements).\n\n## Requirements\n\n-   **PHP version** \u003e= _8.1_\n-   **PHP extensions**:\n    -   [`zip`](https://www.php.net/manual/en/book.zip.php) (native, optional) for `.ZIP`, `.EPUB`, `.CBZ` archives\n    -   [`fileinfo`](https://www.php.net/manual/en/book.fileinfo.php) (native, optional) for better file detection\n    -   [`rar`](https://www.php.net/manual/en/book.rar.php) (optional) for `.RAR`, `.CBR` archives\n    -   [`imagick`](https://www.php.net/manual/en/book.imagick.php) (optional) for `.PDF`\n    -   [`bz2`](https://www.php.net/manual/en/book.bzip2.php) (optional) for `.BZ2` archives\n\n|           Type            | Supported |                                               Requirement                                                |                                  Uses                                  |\n| :-----------------------: | :-------: | :------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------: |\n|  `.zip`, `.epub`, `.cbz`  |    ✅     |                                                   N/A                                                    |   Uses [`zip` extension](https://www.php.net/manual/en/book.zip.php)   |\n| `.tar`, `.tar.gz`, `.cbt` |    ✅     |                                                   N/A                                                    | Uses [`phar` extension](https://www.php.net/manual/en/book.phar.php)\\* |\n|      `.rar`, `.cbr`       |    ✅     | [`rar` PHP extension](https://github.com/cataphract/php-rar) or [`p7zip`](https://www.7-zip.org/) binary |                          PHP `rar` or `p7zip`                          |\n|       `.7z`, `.cb7`       |    ✅     |                                 [`p7zip`](https://www.7-zip.org/) binary                                 |                             `p7zip` binary                             |\n|          `.pdf`           |    ✅     |         Optional (for extraction) [`imagick` PHP extension](https://github.com/Imagick/imagick)          |       [`smalot/pdfparser`](https://github.com/smalot/pdfparser)        |\n\n\\*: for `.tar` archives with password, `.7z` will be used because extension don't support password.\n\n\u003e [!NOTE]\n\u003e\n\u003e Here you can read some installation guides for dependencies\n\u003e\n\u003e -   [`p7zip` guide](https://gist.github.com/ewilan-riviere/85d657f9283fa6af255531d97da5d71d)\n\u003e -   [`rar` PHP extension guide](https://gist.github.com/ewilan-riviere/3f4efd752905abe24fd1cd44412d9db9#winrar)\n\u003e -   [`imagick` PHP extension guide](https://gist.github.com/ewilan-riviere/3f4efd752905abe24fd1cd44412d9db9#imagemagick)\n\n\u003e [!WARNING]\n\u003e\n\u003e -   **On macOS**, for `.rar` extract, you have to [install `rar` binary](https://gist.github.com/ewilan-riviere/85d657f9283fa6af255531d97da5d71d#macos) to extract files, `p7zip` not support `.rar` extraction.\n\u003e -   **On Windows**, for `.pdf` extract, [`imagick` PHP extension](https://github.com/Imagick/imagick) have to work but **my tests failed on this feature**. So to extract PDF pages I advice to use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install).\n\nIf you want more information, you can read section [**About**](#about).\n\n## Features\n\n-   List files as `ArchiveItem` array\n    -   With `getFileItems()` method: list of files\n    -   With `getFileItem(string $path)` method: file corresponding to `path` property\n    -   With `getFirst()` method: first file\n    -   With `getLast()` method: last file\n    -   With `find()` method: find first file that match with `path` property\n    -   With `filter()` method: find all files that match with `path` property\n-   Content of file\n    -   With `getContents()` method: content of file as string (useful for images)\n    -   With `getText()` method: content of text file (binaries files return `null`)\n-   Extract files\n    -   With `extract()` method: extract files to directory\n    -   With `extractAll()` method: extract all files to directory\n-   Stat of archive corresponding to [`stat`](https://www.php.net/manual/en/function.stat.php)\n-   PDF metadata: `getTitle()`, `getAuthor()`, `getSubject()`, `getCreator()`, `getCreationDate()`, `getModDate()`, `getPages()`,\n-   Count files\n-   Create or edit archives, only with `.zip` format\n    -   With `make()` method: create or edit archive\n    -   With `addFiles()` method: add files to archive\n    -   With `addFromString()` method: add string to archive\n    -   With `addDirectory()` and `addDirectories()` methods: add directories to archive\n    -   With `save()` method: save archive\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require kiwilan/php-archive\n```\n\n## Usage\n\n### Read and extract\n\nWith archive file (`.zip`, `.rar`, `.tar`, `.7z`, `epub`, `cbz`, `cbr`, `cb7`, `cbt`, `tar.gz`, `.pdf`).\n\n```php\n$archive = Archive::read('path/to/archive.zip');\n\n$files = $archive-\u003egetFileItems(); // ArchiveItem[]\n$count = $archive-\u003egetCount(); // int of files count\n\n$images = $archive-\u003efilter('jpeg'); // ArchiveItem[] with `jpeg` in their path\n$metadataXml = $archive-\u003efind('metadata.xml'); // First ArchiveItem with `metadata.xml` in their path\n$content = $archive-\u003egetContents($metadataXml); // `metadata.xml` file content\n\n$paths = $archive-\u003eextract('/path/to/directory', [$metadataXml]); // string[] of extracted files paths\n$paths = $archive-\u003eextractAll('/path/to/directory'); // string[] of extracted files paths\n```\n\nPDF files works with same API than archives but with some differences.\n\n```php\n$archive = Archive::read('path/to/file.pdf');\n\n$pdf = $archive-\u003egetPdf(); // Metadata of PDF\n\n$content = $archive-\u003egetContents($archive-\u003egetFirst()); // PDF page as image\n$text = $archive-\u003egetText($archive-\u003egetFirst()); // PDF page as text\n```\n\n### Read from string\n\nYou can read archive from string with `readFromString` method.\n\n```php\n$archive = Archive::readFromString($string);\n```\n\nThis method will try to detect the format of the archive from the string. If you have an error, you can use `readFromString` method with third argument to specify the format of the archive.\n\n```php\n$archive = Archive::readFromString($string, extension: 'zip');\n```\n\n### Password protected\n\nYou can read password protected archives with `read` or `readFromString` method.\n\n\u003e [!WARNING]\n\u003e\n\u003e Works only with archives and not with PDF files.\n\n```php\n$archive = Archive::read('path/to/password-protected-archive.zip', 'password');\n```\n\n### Override binary path\n\nFor `p7zip` binary, you can override the path with `overrideBinaryPath` method.\n\n```php\n$archive = Archive::read($path)-\u003eoverrideBinaryPath('/opt/homebrew/bin/7z');\n```\n\n### Stat\n\nFrom `stat` PHP function: \u003chttps://www.php.net/manual/en/function.stat.php\u003e\n\n\u003e Gives information about a file\n\n```php\n$archive = Archive::read('path/to/file.zip');\n$stat = $archive-\u003estat();\n\n$stat-\u003egetPath(); // Path of file\n$stat-\u003egetDeviceNumber(); // Device number\n$stat-\u003egetInodeNumber(); // Inode number\n$stat-\u003egetInodeProtectionMode(); // Inode protection mode\n$stat-\u003egetNumberOfLinks(); // Number of links\n$stat-\u003egetUserId(); // User ID\n$stat-\u003egetGroupId(); // Group ID\n$stat-\u003egetDeviceType(); // Device type\n$stat-\u003egetSize(); // Size of file\n$stat-\u003egetLastAccessAt(); // Last access time\n$stat-\u003egetCreatedAt(); // Creation time\n$stat-\u003egetModifiedAt(); // Last modification time\n$stat-\u003egetBlockSize(); // Block size\n$stat-\u003egetNumberOfBlocks(); // Number of blocks\n$stat-\u003egetStatus(); // Status\n```\n\n### Create\n\nYou can create archive with method `Archive::make` method.\n\nWorks only with `.zip` archives.\n\n```php\n$archive = Archive::make('path/to/archive.zip');\n$files = [\n    'path/to/file/in/archive-file1.txt' =\u003e 'path/to/real-file1.txt',\n    'path/to/file/in/archive-file2.txt' =\u003e 'path/to/real-file2.txt',\n    'path/to/file/in/archive-file3.txt' =\u003e 'path/to/real-file3.txt',\n];\n\nforeach ($files as $pathInArchive =\u003e $pathToRealFile) {\n    $archive-\u003eaddFile($pathInArchive, $pathToRealFile);\n}\n$archive-\u003eaddFromString('test.txt', 'Hello World!');\n$archive-\u003eaddDirectory('./directory', 'path/to/directory');\n$archive-\u003esave();\n```\n\n### Edit\n\nYou can edit archive with same method `Archive::make` method.\n\n```php\n$archive = Archive::make('path/to/archive.zip');\n$archive-\u003eaddFromString('test.txt', 'Hello World!');\n$archive-\u003esave();\n```\n\n## Testing\n\n```bash\ncomposer test\n```\n\n## About\n\nThis package was inspired by [this excellent post](https://stackoverflow.com/a/39163620/11008206) on StackOverflow which make state of the art of PHP archive handling. The package [Gemorroj/Archive7z](https://github.com/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.\n\nState of the art of PHP archive handling:\n\n-   `.zip` with [ZipArchive](https://www.php.net/manual/en/class.ziparchive.php)\n-   `.tar` with [PharData](https://www.php.net/manual/en/class.phardata.php)\n-   `.rar` with [RarArchive](https://www.php.net/manual/en/class.rararchive.php) if `rar` extension is installed\n-   `.7z` can't be handled with native PHP solution\n\n| Type | Is native |        Solution         |\n| :--: | :-------: | :---------------------: |\n| ZIP  |    ✅     |         Native          |\n| TAR  |    ✅     |         Native          |\n| RAR  |    ❌     | `rar` or `p7zip` binary |\n| 7ZIP |    ❌     |     `p7zip` binary      |\n| PDF  |    ❌     |   `smalot/pdfparser`    |\n\n### Why not full wrapper of `p7zip` binary?\n\nThis solution is used by [Gemorroj/Archive7z](https://github.com/Gemorroj/Archive7z), and it works well. But another problem is the usage of the [`p7zip` fork](https://github.com/p7zip-project/p7zip) which is not the official `p7zip` binary and can be difficult to install on some systems.\n\nPHP 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.\n\n### Case of `rar`\n\nThe [`rar` PHP extension](https://github.com/cataphract/php-rar) 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](https://gist.github.com/ewilan-riviere/3f4efd752905abe24fd1cd44412d9db9#winrar) 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).\n\nBut `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.\n\n### Case of `7zip`\n\nPHP 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](https://gist.github.com/ewilan-riviere/85d657f9283fa6af255531d97da5d71d) if you want to install it.\n\n### Case of `pdf`\n\nPHP 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](https://github.com/Imagick/imagick) you could read [this guide](https://gist.github.com/ewilan-riviere/3f4efd752905abe24fd1cd44412d9db9#imagemagick) if you want to install it.\n\n### eBooks and comics\n\nThis package can handle `.epub`, `.cbz`, `.cbr`, `.cb7`, `.cbt` archives, it's depends on the extension, check [requirements](#requirements) section.\n\n### More\n\nAlternatives:\n\n-   [Gemorroj/Archive7z](https://github.com/Gemorroj/Archive7z): handle many archives with [p7zip-project/p7zip](https://github.com/p7zip-project/p7zip) binary\n-   [splitbrain/php-archive](https://github.com/splitbrain/php-archive): native PHP solution to handle `.zip` and `.tar` archives\n-   [maennchen/ZipStream-PHP](https://github.com/maennchen/ZipStream-PHP): A fast and simple streaming zip file downloader for PHP. Using this library will save you from having to write the Zip to disk.\n\nDocumentation:\n\n-   List files in `.7z`, `.rar` and `.tar` archives using PHP: \u003chttps://stackoverflow.com/a/39163620/11008206\u003e\n-   Compression and Archive Extensions: \u003chttps://www.php.net/manual/en/refs.compression.php\u003e\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Credits\n\n-   [Ewilan Riviere](https://github.com/ewilan-riviere)\n-   [All Contributors](../../contributors)\n-   [spatie](https://github.com/spatie) for `spatie/package-skeleton-php` and `spatie/temporary-directory`\n-   [`smalot/pdfparser`](https://github.com/smalot/pdfparser) for PDF parser\n-   [`7-zip`](https://www.7-zip.org/) for `p7zip` binary\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n\n[\u003cimg src=\"https://user-images.githubusercontent.com/48261459/201463225-0a5a084e-df15-4b11-b1d2-40fafd3555cf.svg\" height=\"120rem\" width=\"100%\" /\u003e](https://github.com/kiwilan)\n\n[version-src]: https://img.shields.io/packagist/v/kiwilan/php-archive.svg?style=flat\u0026colorA=18181B\u0026colorB=777BB4\n[version-href]: https://packagist.org/packages/kiwilan/php-archive\n[php-version-src]: https://img.shields.io/static/v1?style=flat\u0026label=PHP\u0026message=v8.1\u0026color=777BB4\u0026logo=php\u0026logoColor=ffffff\u0026labelColor=18181b\n[php-version-href]: https://www.php.net/\n[downloads-src]: https://img.shields.io/packagist/dt/kiwilan/php-archive.svg?style=flat\u0026colorA=18181B\u0026colorB=777BB4\n[downloads-href]: https://packagist.org/packages/kiwilan/php-archive\n[license-src]: https://img.shields.io/github/license/kiwilan/php-archive.svg?style=flat\u0026colorA=18181B\u0026colorB=777BB4\n[license-href]: https://github.com/kiwilan/php-archive/blob/main/README.md\n[tests-src]: https://img.shields.io/github/actions/workflow/status/kiwilan/php-archive/run-tests.yml?branch=main\u0026label=tests\u0026style=flat\u0026colorA=18181B\n[tests-href]: https://github.com/kiwilan/php-archive/actions/workflows/run-tests.yml\n[codecov-src]: https://img.shields.io/codecov/c/gh/kiwilan/php-archive/main?style=flat\u0026colorA=18181B\u0026colorB=777BB4\n[codecov-href]: https://codecov.io/gh/kiwilan/php-archive\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiwilan%2Fphp-archive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiwilan%2Fphp-archive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiwilan%2Fphp-archive/lists"}