**🇷🇺 Русский** · [🇬🇧 English](docs/en/README.md) · [🇩🇪 Deutsch](docs/de/README.md) · [🇫🇷 Français](docs/fr/README.md) · [🇪🇸 Español](docs/es/README.md) · [🇮🇹 Italiano](docs/it/README.md)

# CloudCastle Archive **22 формата архивов в одном пакете на чистом PHP. Потоково, без временных файлов, с памятью порядка размера чанка — а не размера архива.** [![Packagist](https://img.shields.io/packagist/v/cloud-castle/archive?label=packagist&color=3b82f6)](https://packagist.org/packages/cloud-castle/archive) [![Downloads](https://img.shields.io/packagist/dt/cloud-castle/archive?label=downloads&color=f97316)](https://packagist.org/packages/cloud-castle/archive) [![PHP](https://img.shields.io/packagist/php-v/cloud-castle/archive?color=777bb4)](https://packagist.org/packages/cloud-castle/archive) [![License](https://img.shields.io/packagist/l/cloud-castle/archive?color=22c55e)](LICENSE) [![GitVerse](https://img.shields.io/badge/GitVerse-cloud--castle%2Farchive-1f6feb)](https://gitverse.ru/cloud-castle/archive) [![CI](https://img.shields.io/badge/CI-quality-22c55e)](https://gitverse.ru/cloud-castle/archive/actions) [![Pages](https://img.shields.io/badge/docs-pages-0ea5e9)](https://cloud-castle.gitverse.site/archive/) [![PHPStan](https://img.shields.io/badge/PHPStan-max-2a2a2a)](phpstan.neon) [![Psalm](https://img.shields.io/badge/Psalm-level%201-5c21a5)](psalm.xml) [![PHPMD](https://img.shields.io/badge/PHPMD-clean-0b7285)](phpmd.xml) [![PHPCS](https://img.shields.io/badge/PHPCS-PSR--12-1c7ed6)](phpcs.xml.dist) [![Coverage](https://img.shields.io/badge/coverage-100.00%25-brightgreen)](phpunit.xml.dist) [![Infection MSI](https://img.shields.io/badge/Infection%20MSI-100.00%25-f59e0b)](infection.json.dist) [![OpenSSF Scorecard](https://img.shields.io/badge/OpenSSF-Scorecard-1f883d)](SECURITY.md) ```php use CloudCastle\Archive\Archive; // Упаковать каталог — формат выбирается по расширению Archive::pack('/var/www/project', '/backup/project.tar.gz'); // Распаковать что угодно — формат определяется по сигнатуре Archive::extract('/incoming/delivery.7z', '/data/unpacked'); // Перепаковать из формата в формат, не разворачивая архив на диск Archive::convert('/incoming/delivery.7z', '/data/delivery.zip'); ``` ## Содержание - [Зачем этот пакет](#зачем-этот-пакет) - [Установка](#установка) - [Быстрый старт](#быстрый-старт) - [Поддерживаемые форматы](#поддерживаемые-форматы) - [Возможности](#возможности) - [Сравнение с аналогами](#сравнение-с-аналогами) - [Производительность](#производительность) - [Потребление памяти](#потребление-памяти) - [Безопасность](#безопасность) - [Качество кода](#качество-кода) - [Честно о плюсах и минусах](#честно-о-плюсах-и-минусах) - [Когда его стоит брать](#когда-его-стоит-брать) - [Документация](#документация) ## Зачем этот пакет Библиотеки архивации в PHP обычно решают одну задачу: работают с одним-двумя форматами, требуют расширений (`ext-zip`, `ext-rar`) или внешних утилит, а большие архивы разворачивают в памяти целиком. CloudCastle Archive устроен иначе: - **Один фасад на все форматы.** `Archive::pack()`, `Archive::extract()`, `Archive::convert()` работают одинаково для ZIP, 7z, tar.zst, ISO и остальных. - **Потоковость как основа.** Внутри всё построено на генераторах: архив читается и пишется кусками, поэтому 50-гигабайтный образ обрабатывается на том же лимите памяти, что и файл на мегабайт. - **Собственные кодеки.** LZMA/LZMA2, XZ, LZ4, BCJ и Delta реализованы на чистом PHP — 7z и tar.xz читаются там, где никаких расширений нет. - **Безопасность по умолчанию.** Zip-slip, архивные бомбы, символические ссылки и подделанные заголовки блокируются без дополнительной настройки. ## Установка ```bash composer require cloud-castle/archive ``` Требуется **PHP 8.1+**; ни одно расширение не входит в зависимости пакета. ZIP, TAR, tar.gz, tar.lz4, 7z, ISO, CAB, CPIO, AR/DEB и PHAR работают на голом PHP — включая чтение LZMA, LZMA2 и XZ собственными декодерами. Остальное зависит от окружения: `tar.xz` читается без расширений, а записывается через `ext-xz`; `tar.bz2`, `tar.zst` и `tar.br` требуют `ext-bz2`, `ext-zstd` и `ext-brotli` соответственно; RAR читается через `ext-rar` либо системный `unrar`. Чего нет в окружении — о том пакет сообщает явной ошибкой, а не молчаливой порчей архива; полная таблица зависимостей — в [справочнике форматов](wiki/docs/ru/formats.md). ## Быстрый старт ```php use CloudCastle\Archive\Archive; use CloudCastle\Archive\ArchiveOptions; use CloudCastle\Archive\EncryptionMethod; // Собрать архив по частям Archive::create('/tmp/report.zip') ->addFile('/data/report.pdf', 'docs/report.pdf') ->addDirectory('/data/images', 'images') ->addFromString('meta.json', json_encode($meta, JSON_THROW_ON_ERROR)) ->finish(); // Прочитать, не распаковывая на диск $reader = Archive::open('/tmp/report.zip'); foreach ($reader->files() as $entry) { echo $entry->name, ' — ', $entry->size, " байт\n"; } $json = $reader->read('meta.json'); $reader->close(); // Правка готового архива: удалить, переименовать, заменить, дописать Archive::edit('/tmp/report.zip') ->delete('docs/draft.pdf') ->rename('meta.json', 'meta/report.json') ->save(); // Зашифрованный архив: WinZip AES-256 $options = ArchiveOptions::default()->withPassword('секрет', EncryptionMethod::Aes256); Archive::pack('/data/private', '/backup/private.zip', null, $options); ``` ## Поддерживаемые форматы | Семейство | Форматы | Чтение | Запись | | --- | --- | --- | --- | | ZIP | `.zip` (Zip64, ZipCrypto, WinZip AES-128/192/256) | ✅ | ✅ | | TAR | `.tar` (ustar, PAX, GNU), `.tar.gz`, `.tar.bz2`, `.tar.xz`, `.tar.zst`, `.tar.lz4`, `.tar.br` | ✅ | ✅ | | 7-Zip | `.7z` (LZMA, LZMA2, Copy, Delta, BCJ, солид-блоки, AES-256 с шифрованием заголовка) | ✅ | ✅ | | RAR | `.rar` (через `ext-rar` либо системный `unrar`) | ✅ | — | | Образы | `.iso` (ISO 9660, Joliet, Rock Ridge) | ✅ | ✅ | | Пакеты | `.deb`, `.ar`, `.cpio` (newc/odc), `.cab`, `.phar` | ✅ | ✅ | | Одиночные | `.gz`, `.bz2`, `.xz`, `.zst`, `.lz4`, `.br` | ✅ | ✅ | Знаки в таблице описывают возможности пакета; `tar.bz2`, `tar.zst`, `tar.br` и запись `tar.xz` дополнительно требуют расширений PHP. Зависимости по каждому формату и его особенности — в [справочнике форматов](wiki/docs/ru/formats.md). ## Возможности | Возможность | **archive** | unified-archive | zip | php-archive | zipstream-php | archive_tar | 🏆 Победитель | | --- | --- | --- | --- | --- | --- | --- | --- | | **Форматы чтения** | | | | | | | | | ZIP | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | 🏆 **archive**, unified-archive, zip, php-archive | | TAR (ustar/PAX/GNU) | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ | 🏆 **archive**, unified-archive, php-archive, archive_tar | | tar.gz / tgz | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ | 🏆 **archive**, unified-archive, php-archive, archive_tar | | tar.bz2 | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ | 🏆 **archive**, unified-archive, php-archive, archive_tar | | tar.xz | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive**, unified-archive | | tar.zst | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | tar.lz4 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | tar.br (brotli) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | 7z | ✅ | 🟡 | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | RAR | ✅ | 🟡 | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | CAB | ✅ | 🟡 | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | ISO 9660 (+Joliet, Rock Ridge) | ✅ | 🟡 | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | CPIO (newc/odc) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | AR / DEB | ✅ | 🟡 | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | PHAR (без ext-phar) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Одиночные gz/bz2/xz/zst/lz4/br | ✅ | 🟡 | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | **Форматы записи** | | | | | | | | | Запись ZIP | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | 🏆 **archive**, unified-archive, zip, php-archive, zipstream-php | | Запись TAR и tar.* | ✅ | ✅ | ❌ | ✅ | ❌ | ✅ | 🏆 **archive**, unified-archive, php-archive, archive_tar | | Запись 7z | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Запись CAB | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Запись ISO 9660 | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Запись CPIO | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Запись AR/DEB | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Запись PHAR | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | **Потоковость и память** | | | | | | | | | Чтение генераторами (O(chunk)) | ✅ | ❌ | 🟡 | 🟡 | ❌ | ❌ | 🏆 **archive** | | Запись генераторами (O(chunk)) | ✅ | ❌ | 🟡 | ❌ | ✅ | ❌ | 🏆 **archive**, zipstream-php | | Архив больше доступной памяти | ✅ | ❌ | 🟡 | 🟡 | ✅ | ❌ | 🏆 **archive**, zipstream-php | | Запись в сетевой поток без файла | ✅ | ❌ | 🟡 | ❌ | ✅ | ❌ | 🏆 **archive**, zipstream-php | | Zip64 для потоков неизвестной длины | ✅ | ❌ | ✅ | ❌ | ✅ | ❌ | 🏆 **archive**, zip, zipstream-php | | **Шифрование** | | | | | | | | | ZipCrypto | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | 🏆 **archive**, zip | | WinZip AES-128/192/256 | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | 🏆 **archive**, zip | | Проверка HMAC при распаковке | ✅ | ❌ | 🟡 | ❌ | ❌ | ❌ | 🏆 **archive** | | Чтение зашифрованных 7z (AES-256) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Чтение зашифрованных RAR | ✅ | 🟡 | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Шифрование заголовка 7z (-mhe=on) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | **Безопасность** | | | | | | | | | Защита от zip-slip | ✅ | 🟡 | ✅ | 🟡 | ❌ | ❌ | 🏆 **archive**, zip | | Лимит числа записей | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Лимит распакованного объёма | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Лимит степени сжатия (архивные бомбы) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Политика символических ссылок | ✅ | ❌ | 🟡 | ❌ | ❌ | ❌ | 🏆 **archive** | | Запуск внешних утилит без шелла | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Отказ от unserialize при чтении PHAR | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | **Работа с путями и записями** | | | | | | | | | Абсолютные и относительные пути | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 🏆 **archive**, unified-archive, zip, php-archive, zipstream-php, archive_tar | | Каталоги, пустые каталоги | ✅ | ✅ | ✅ | ✅ | 🟡 | ✅ | 🏆 **archive**, unified-archive, zip, php-archive, archive_tar | | Символические ссылки | ✅ | ❌ | 🟡 | ❌ | ❌ | ✅ | 🏆 **archive**, archive_tar | | Права и метки времени | ✅ | 🟡 | ✅ | 🟡 | 🟡 | ✅ | 🏆 **archive**, zip, archive_tar | | Комментарии архива и записей | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | 🏆 **archive**, zip | | Фильтрация записей при упаковке | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | 🏆 **archive**, zip | | Отчёт о прогрессе | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | **Операции** | | | | | | | | | Конвертация формат → формат | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Автоопределение формата по сигнатуре | ✅ | 🟡 | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Проверка целостности (test) | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | 🏆 **archive**, zip | | Единый фасад для всех форматов | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive**, unified-archive | | Сжатие и распаковка одиночных файлов | ✅ | 🟡 | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Удаление записей из готового архива | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | 🏆 **archive**, unified-archive, zip | | Переименование записей | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | 🏆 **archive**, zip | | Замена содержимого записи | ✅ | 🟡 | ✅ | ❌ | ❌ | ❌ | 🏆 **archive**, zip | | Дописывание в готовый архив | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | 🏆 **archive**, unified-archive, zip, archive_tar | | Правка архива потоком, без распаковки | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Консольная утилита | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive**, unified-archive | | **Качество и сопровождение** | | | | | | | | | Строгая типизация (strict_types) | ✅ | ❌ | ✅ | 🟡 | ✅ | ❌ | 🏆 **archive**, zip, zipstream-php | | PHPStan max / Psalm level 1 | ✅ | ❌ | 🟡 | ❌ | 🟡 | ❌ | 🏆 **archive** | | Работает без внешних утилит | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | 🏆 **archive**, zip, php-archive, zipstream-php, archive_tar | | Без обязательных ext-расширений | ✅ | ❌ | ❌ | 🟡 | ✅ | 🟡 | 🏆 **archive**, zipstream-php | | **Итого возможностей** | **64** | **13** | **18** | **9** | **9** | **10** | 🏆 **archive** | ## Сравнение с аналогами Сравнение идёт с пятью самыми распространёнными PHP-пакетами архивации. Таблицы ниже собираются автоматически (`composer docs:sync`) из фактических прогонов, а не из обещаний документации. | Пакет | Версия | | --- | --- | | `cloud-castle/archive` | v1.2.0 | | `wapmorgan/unified-archive` | 1.3.1 | | `nelexa/zip` | 4.0.2 | | `splitbrain/php-archive` | 1.5.1 | | `maennchen/zipstream-php` | 3.1.1 | | `pear/archive_tar` | 1.6.1 | ## Производительность Замеры воспроизводятся командой `composer bench`: каждый участник каждого сценария выполняется в отдельном процессе, участники чередуются раунд за раундом, берётся лучшее время. Так дрейф фоновой нагрузки не достаётся целиком одному пакету. Xdebug на время замеров выключен: он замедляет PHP-код во много раз сильнее, чем код расширений, и исказил бы сравнение. | Сценарий (мс, меньше — лучше) | **archive** | unified-archive | zip | php-archive | zipstream-php | archive_tar | 🏆 Победитель | | --- | --- | --- | --- | --- | --- | --- | --- | | Упаковка каталога в ZIP (120 файлов, ~6 МиБ) | 43.76 | 47.07 | 105.41 | 58.50 | 68.45 | — | 🏆 **archive** | | Распаковка ZIP (120 файлов, ~6 МиБ) | 26.81 | 23.16 | 26.80 | 44.67 | — | — | 🏆 unified-archive | | Упаковка файла 64 МиБ в tar.gz | 1 448.57 | 1 692.75 | — | 1 571.05 | — | 1 638.49 | 🏆 **archive** | | Упаковка каталога в tar.gz (120 файлов, ~6 МиБ) | 63.09 | 629.95 | — | 64.44 | — | 72.67 | 🏆 **archive** | **Как это читать.** Упаковку ZIP и оба сценария tar.gz наш пакет выигрывает у всех — в том числе у `unified-archive`, который для ZIP вызывает расширение `ext-zip` на C. Файлы до 256 КиБ сжимаются одним вызовом zlib, и их размеры сразу пишутся в локальный заголовок, а tar.gz в файл сжимается встроенным фильтром zlib прямо на выходном потоке: данные не возвращаются в PHP-код на каждом куске. Распаковку ZIP выигрывает `unified-archive`: чтение, распаковка и запись файлов у него целиком проходят внутри libzip. Мы медленнее примерно на 15 % и при этом по умолчанию восстанавливаем права и время изменения файлов — около 1.3 мс на 120 файлов, — чего `unified-archive` не делает. Там, где `ext-zip` нет, альтернативы у него нет вовсе: без расширения `unified-archive` ZIP не откроет. ## Потребление памяти Цифра — пик памяти самой библиотеки: базовая линия процесса снимается до первого обращения к участнику и вычитается, поэтому старт PHP и автозагрузчик в неё не попадают. На файле в 64 МиБ пик тот же, что на каталоге в 6 МиБ, — это и есть признак потоковости. Здесь мы не первые, и это осознанный компромисс: `splitbrain/php-archive` и `pear/archive_tar` держат на 0.4–0.7 МиБ меньше, а наш пакет тратит эти буферы на скорость — копирование кусками по 1 МиБ и чтение небольших файлов целиком. Разница не зависит от размера архива. | Сценарий (МиБ, меньше — лучше) | **archive** | unified-archive | zip | php-archive | zipstream-php | archive_tar | 🏆 Победитель | | --- | --- | --- | --- | --- | --- | --- | --- | | Упаковка каталога в ZIP (120 файлов, ~6 МиБ) | 1.17 | 1.22 | 2.26 | 0.65 | 16.61 | — | 🏆 php-archive | | Распаковка ZIP (120 файлов, ~6 МиБ) | 0.87 | 1.18 | 1.22 | 0.48 | — | — | 🏆 php-archive | | Упаковка файла 64 МиБ в tar.gz | 1.19 | 1.70 | — | 2.34 | — | 0.80 | 🏆 archive_tar | | Упаковка каталога в tar.gz (120 файлов, ~6 МиБ) | 1.19 | 7.95 | — | 1.34 | — | 0.81 | 🏆 archive_tar | Пик — половина картины. Вторая половина — утечки: сколько памяти не возвращается после десятков однотипных операций подряд. Процесс, обрабатывающий архивы часами, падает именно от этого. | Сценарий (КиБ за серию, меньше — лучше) | **archive** | unified-archive | zip | php-archive | zipstream-php | archive_tar | 🏆 Победитель | | --- | --- | --- | --- | --- | --- | --- | --- | | Упаковка каталога в ZIP (120 файлов, ~6 МиБ) | 0.37 | 0.37 | 0.37 | 0.37 | 0.37 | — | 🏆 **archive**, unified-archive, zip, php-archive, zipstream-php | | Распаковка ZIP (120 файлов, ~6 МиБ) | 0.37 | 0.37 | 0.37 | 0.37 | — | — | 🏆 **archive**, unified-archive, zip, php-archive | | Упаковка файла 64 МиБ в tar.gz | 0.37 | 77.79 | — | 0.37 | — | 0.37 | 🏆 **archive**, php-archive, archive_tar | | Упаковка каталога в tar.gz (120 файлов, ~6 МиБ) | 0.37 | 234.30 | — | 0.37 | — | 0.37 | 🏆 **archive**, php-archive, archive_tar | ## Безопасность Каждая защита включена по умолчанию и проверяется тестами набора `security`: - **Zip-slip.** Имена записей нормализуются, выход за пределы каталога назначения отклоняется до открытия файла. - **Архивные бомбы.** Лимиты на число записей, суммарный распакованный объём и степень сжатия (`withMaxEntries`, `withMaxTotalSize`, `withMaxRatio`). - **Символические ссылки.** Политика `SymlinkPolicy`: пропустить, отклонить или распаковать с проверкой цели. - **Шифрование.** В ZIP пароль сначала сверяется двухбайтовым верификатором, а код аутентификации HMAC-SHA1 проверяется по окончании записи — так устроен формат WinZip AES. Зашифрованные 7z читаются целиком, включая архивы с зашифрованным заголовком (`-mhe=on`). - **Внешние утилиты.** Запускаются без командной оболочки, аргументы передаются массивом — инъекция команд невозможна. - **PHAR.** Читается собственным парсером без `unserialize()`. | Стандарт | **archive** | unified-archive | zip | php-archive | zipstream-php | archive_tar | 🏆 Победитель | | --- | --- | --- | --- | --- | --- | --- | --- | | SECURITY.md с политикой раскрытия | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | 🏆 **archive**, zipstream-php, archive_tar | | Реакция на security advisories | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | composer audit в CI | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | 🏆 **archive**, zipstream-php | | Статический анализ безопасности | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | 🏆 **archive**, zipstream-php | | Защита от CWE-22 (обход пути) | ✅ | ✅ | ✅ | ❌ | ❌ | ✅ | 🏆 **archive**, unified-archive, zip, archive_tar | | Защита от CWE-409 (архивные бомбы) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Защита от CWE-502 (десериализация) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 🏆 **archive**, unified-archive, zip, php-archive, zipstream-php, archive_tar | | Защита от CWE-78 (инъекция команд) | ✅ | ❌ | ✅ | ✅ | ❌ | ✅ | 🏆 **archive**, zip, php-archive, archive_tar | | Проверка целостности при распаковке | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 🏆 **archive**, unified-archive, zip, php-archive, zipstream-php, archive_tar | ## Качество кода | Метрика | **archive** | unified-archive | zip | php-archive | zipstream-php | archive_tar | 🏆 Победитель | | --- | --- | --- | --- | --- | --- | --- | --- | | Строгая типизация во всех файлах | 100% | 0% | 100% | 0% | 100% | 0% | 🏆 **archive**, zip, zipstream-php | | Уровень PHPStan | max | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Уровень Psalm | 1 | ❌ | ❌ | ❌ | 1 | ❌ | 🏆 **archive**, zipstream-php | | Покрытие тестами, строки | 100.00% | — | — | — | — | — | 🏆 **archive** | | Мутационный индекс (MSI) | 100.00% | — | — | — | — | — | 🏆 **archive** | | Слоевые правила (deptrac) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | 🏆 **archive** | | Публичный API задокументирован | 99% | 75% | 68% | 99% | 72% | 98% | 🏆 **archive**, php-archive | ### Замечания анализаторов Каждый пакет прогнан одними и теми же инструментами с общепризнанными наборами правил — PSR-12 у PHPCS и стандартные наборы PHPMD, — а не нашими конфигами: иначе это была бы проверка чужого кода на соответствие нашим вкусам. Счёт нормирован на тысячу строк. | Проверка (замечаний на 1000 строк, меньше — лучше) | **archive** | unified-archive | zip | php-archive | zipstream-php | archive_tar | 🏆 Победитель | | --- | --- | --- | --- | --- | --- | --- | --- | | Стиль PSR-12 (PHPCS) | 0.00 | 93.52 | 3.74 | 49.80 | 10.10 | 78.85 | 🏆 **archive** | | Размер кода (PHPMD) | 3.54 | 4.66 | 3.81 | 5.95 | 3.21 | 15.53 | 🏆 zipstream-php | | Дизайн (PHPMD) | 0.37 | 0.35 | 0.31 | 0.00 | 0.92 | 0.40 | 🏆 php-archive | | Именование (PHPMD) | 1.75 | 2.57 | 3.27 | 4.09 | 19.27 | 4.38 | 🏆 **archive** | | Мёртвый код (PHPMD) | 0.00 | 5.36 | 1.01 | 0.00 | 0.00 | 2.79 | 🏆 **archive**, php-archive, zipstream-php | | Чистый код (PHPMD) | 37.86 | 21.46 | 12.76 | 37.90 | 14.23 | 114.30 | 🏆 zip | | Синтаксис на текущем PHP | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 🏆 **archive**, unified-archive, zip, php-archive, zipstream-php, archive_tar | Три строки мы проигрываем и не прячем это. 716 из наших замечаний «чистого кода» даёт одно правило `StaticAccess`: оно считает дефектом каждый статический вызов, а потоковый API держится на статических фабриках (`Archive::create()`, `TarHeader::parse()`). Отказ от них дал бы другой публичный интерфейс, а не более чистый код. Размер кода и дизайн мы уступаем пакетам, решающим заметно более узкую задачу: `zipstream-php` только пишет ZIP в поток, `php-archive` знает два формата. ## Честно о плюсах и минусах **Сильные стороны** - Больше форматов, чем у всех сравниваемых пакетов вместе взятых. - Потоковая архитектура: расход памяти не зависит от размера архива — библиотека занимает около 1.2 МиБ и на файле в 64 МиБ, и на каталоге в 6 МиБ. - Самая быстрая упаковка ZIP и tar.gz среди сравниваемых пакетов, включая обёртку над `ext-zip`. - Работает без обязательных расширений PHP и внешних утилит. - Конвертация между форматами без промежуточной распаковки на диск. - Защиты от zip-slip и архивных бомб встроены, а не вынесены в примеры. **Слабые стороны — без прикрас** - **Пакет моложе аналогов** и пока менее распространён: у него нет многолетней истории эксплуатации, которая есть у `pear/archive_tar` или `nelexa/zip`. - **RAR только на чтение.** Формат закрыт, запись не реализована и не планируется. - **Распаковка ZIP через `ext-zip` быстрее.** `unified-archive`, отдающий работу libzip, распаковывает ZIP примерно на 15 % быстрее: весь путь данных у него на C, а мы вдобавок восстанавливаем права и время файлов. - **Память — не минимальная.** В пике библиотека занимает на 0.4–0.7 МиБ больше, чем `splitbrain/php-archive` и `pear/archive_tar`: буферы потрачены на скорость. С размером архива потребление не растёт. - **PHPMD ругается на статические вызовы.** По стандартному набору Clean Code у нас плотность замечаний выше, чем у `nelexa/zip`: 716 из них даёт правило `StaticAccess`. Потоковый API держится на статических фабриках (`Archive::create()`, `TarHeader::parse()`), и отказ от них означал бы другой публичный интерфейс, а не более чистый код. Остальные наборы правил — за нами, таблица замечаний анализаторов выше. Других минусов мы не декларируем: по функциональности, скорости, безопасности и качеству кода пакет сопоставим с лучшими в своей категории или превосходит их — это видно в таблицах выше, и их можно пересобрать у себя одной командой. ## Когда его стоит брать | Ситуация | Рекомендация | | --- | --- | | Приём файлов от пользователей, распаковка на сервере | **Да.** Лимиты бомб и zip-slip включены по умолчанию. | | Резервное копирование, выгрузки, отчёты | **Да.** Потоковая запись; tar.gz и tar.lz4 не требуют расширений, tar.zst — `ext-zstd`. | | Разбор чужих форматов поставки (7z, ISO, DEB, CAB) | **Да.** Единственный пакет, читающий их без внешних утилит. | | Отдача архива пользователю «на лету» в HTTP-поток | **Да.** Запись идёт в поток, память не растёт. | | Нужно поправить готовый архив: убрать секрет, подменить конфиг, дописать манифест | **Да.** `Archive::edit()` пересобирает архив потоком и не портит исходник при сбое. | | Нужен только ZIP, `ext-zip` есть и всё устраивает | Можно взять `nelexa/zip` — узкоспециализированный инструмент. | | Нужна запись RAR | **Нет.** Формат закрыт, записи нет ни у кого в PHP. | | PHP младше 8.1 | **Нет.** Пакет использует типы и возможности 8.1+. | ## Документация - [Справочник форматов](wiki/docs/ru/formats.md) - [Возможности по разделам](wiki/docs/ru/features.md) - [Безопасность](wiki/docs/ru/security.md) - [Производительность и память](wiki/docs/ru/performance.md) - [Рецепты](wiki/docs/ru/recipes.md) - [Справочник API](wiki/docs/ru/api.md) ## Консольная утилита Пакет ставит команду `archive`: те же возможности из терминала, без единой строки кода. ```bash vendor/bin/archive pack /data/report /backup/report.zip vendor/bin/archive list /backup/report.zip vendor/bin/archive convert /backup/report.zip /backup/report.tar.zst vendor/bin/archive delete /backup/report.zip secrets/.env vendor/bin/archive test /backup/report.tar.zst vendor/bin/archive extract /backup/report.tar.zst /restore ``` Команда возвращает 0 при успехе, 1 при ошибке работы с архивом и 2 при неверном вызове — так её удобно ставить в скрипты. Полный список — в `vendor/bin/archive help`. ## Совместимость Версии нумеруются по [SemVer](https://semver.org/lang/ru/). Обещание обратной совместимости распространяется на классы, которые **не** помечены `@internal`: фасад `Archive`, построитель, читатель, редактор, опции, перечисления, отчёты, исключения и контракты — всего 54 класса, их полный список лежит в `tests/Fixtures/public-api.txt` и проверяется тестом. Драйверы форматов, кодеки и примитивы ввода-вывода помечены `@internal`: они решают задачу за фасадом и могут меняться в любом выпуске. Если чего-то не хватает в публичном слое — это повод завести обсуждение, а не обращаться к внутреннему классу напрямую. Минимальная версия PHP — 8.1; она поднимается только мажорным выпуском. ## Участие и поддержка - [Как участвовать](CONTRIBUTING.md) - [Кодекс поведения](CODE_OF_CONDUCT.md) - [Политика безопасности](SECURITY.md) - [История изменений](CHANGELOG.md) Лицензия — [MIT](LICENSE). **🇷🇺 Русский** · [🇬🇧 English](docs/en/README.md) · [🇩🇪 Deutsch](docs/de/README.md) · [🇫🇷 Français](docs/fr/README.md) · [🇪🇸 Español](docs/es/README.md) · [🇮🇹 Italiano](docs/it/README.md)

archive

Описание

Релизы1

Языки

Релизы
1