From 4a436569daee45db53de5487e4aac408c99e254d Mon Sep 17 00:00:00 2001 From: Ne-Lexa Date: Wed, 24 Feb 2021 12:06:08 +0300 Subject: [PATCH] update README --- README.RU.md | 369 +++++++++++++++++++++++++++++---------------------- README.md | 8 +- 2 files changed, 214 insertions(+), 163 deletions(-) diff --git a/README.RU.md b/README.RU.md index d336771..0de0a3d 100644 --- a/README.RU.md +++ b/README.RU.md @@ -2,41 +2,42 @@ `PhpZip` - php библиотека для продвинутой работы с ZIP-архивами. -[![Build Status](https://github.com/Ne-Lexa/php-zip/workflows/build/badge.svg)](https://github.com/Ne-Lexa/php-zip/actions) +[![Packagist Version](https://img.shields.io/packagist/v/nelexa/zip.svg)](https://packagist.org/packages/nelexa/zip) +[![Packagist Downloads](https://img.shields.io/packagist/dt/nelexa/zip.svg?color=%23ff007f)](https://packagist.org/packages/nelexa/zip) [![Code Coverage](https://scrutinizer-ci.com/g/Ne-Lexa/php-zip/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/Ne-Lexa/php-zip/?branch=master) -[![Latest Stable Version](https://poser.pugx.org/nelexa/zip/v/stable)](https://packagist.org/packages/nelexa/zip) -[![Total Downloads](https://poser.pugx.org/nelexa/zip/downloads)](https://packagist.org/packages/nelexa/zip) -[![License](https://poser.pugx.org/nelexa/zip/license)](https://packagist.org/packages/nelexa/zip) +[![Build Status](https://github.com/Ne-Lexa/php-zip/workflows/build/badge.svg)](https://github.com/Ne-Lexa/php-zip/actions) +[![License](https://img.shields.io/packagist/l/nelexa/zip.svg)](https://github.com/Ne-Lexa/php-zip/blob/master/LICENSE) + [English Documentation](README.md) Содержание ---------- -- [Функционал](#Features) -- [Требования](#Requirements) -- [Установка](#Installation) -- [Примеры](#Examples) -- [Глоссарий](#Glossary) -- [Документация](#Documentation) - + [Обзор методов класса `\PhpZip\ZipFile`](#Documentation-Overview) - + [Создание/Открытие ZIP-архива](#Documentation-Open-Zip-Archive) - + [Чтение записей из архива](#Documentation-Open-Zip-Entries) - + [Перебор записей/Итератор](#Documentation-Zip-Iterate) - + [Получение информации о записях](#Documentation-Zip-Info) - + [Добавление записей в архив](#Documentation-Add-Zip-Entries) - + [Удаление записей из архива](#Documentation-Remove-Zip-Entries) - + [Работа с записями и с архивом](#Documentation-Entries) - + [Работа с паролями](#Documentation-Password) - + [Отмена изменений](#Documentation-Unchanged) - + [Сохранение файла или вывод в браузер](#Documentation-Save-Or-Output-Entries) - + [Закрытие архива](#Documentation-Close-Zip-Archive) -- [Запуск тестов](#Running-Tests) -- [История изменений](#Changelog) -- [Обновление версий](#Upgrade) - + [Обновление с версии 2 до версии 3.0](#Upgrade-v2-to-v3) - + [Обновление с версии 3 до версии 4](#Upgrade-v3-to-v4) +- [Функционал](#функционал) +- [Требования](#требования) +- [Установка](#установка) +- [Примеры](#примеры) +- [Глоссарий](#глоссарий) +- [Документация](#документация) + + [Обзор методов класса `\PhpZip\ZipFile`](#обзор-методов-класса-phpzipzipfile) + + [Создание/Открытие ZIP-архива](#созданиеоткрытие-zip-архива) + + [Чтение записей из архива](#чтение-записей-из-архива) + + [Перебор записей/Итератор](#перебор-записейитератор) + + [Получение информации о записях](#получение-информации-о-записях) + + [Добавление записей в архив](#добавление-записей-в-архив) + + [Удаление записей из архива](#удаление-записей-из-архива) + + [Работа с записями и с архивом](#работа-с-записями-и-с-архивом) + + [Работа с паролями](#работа-с-паролями) + + [Отмена изменений](#отмена-изменений) + + [Сохранение файла или вывод в браузер](#сохранение-файла-или-вывод-в-браузер) + + [Закрытие архива](#закрытие-архива) +- [Запуск тестов](#запуск-тестов) +- [История изменений](#история-изменений) +- [Обновление версий](#обновление-версий) + + [Обновление с версии 3 до версии 4](#обновление-с-версии-3-до-версии-4) + + [Обновление с версии 2 до версии 3](#обновление-с-версии-2-до-версии-3) -### Функционал +### Функционал - Открытие и разархивирование ZIP-архивов. - Создание ZIP-архивов. - Модификация ZIP-архивов. @@ -63,17 +64,17 @@ + Поддержка методов шифрования `Traditional PKWARE Encryption (ZipCrypto)` и `WinZIP AES Encryption (128, 192 или 256 bit)`. + Установка метода шифрования для всех или для отдельных записей в архиве. -### Требования +### Требования - `PHP` 7.4 или ^8.0 (предпочтительно 64-bit). - Опционально php-расширение `bzip2` для поддержки BZIP2 компрессии. - Опционально php-расширение `openssl` для `WinZip Aes Encryption` шифрования. -### Установка +### Установка `composer require nelexa/zip` Последняя стабильная версия: [![Latest Stable Version](https://poser.pugx.org/nelexa/zip/v/stable)](https://packagist.org/packages/nelexa/zip) -### Примеры +### Примеры ```php // создание нового архива $zipFile = new \PhpZip\ZipFile(); @@ -103,89 +104,94 @@ finally{ ``` Другие примеры можно посмотреть в папке `tests/`. -### Глоссарий +### Глоссарий **Запись в ZIP-архиве (Zip Entry)** - файл или папка в ZIP-архиве. У каждой записи в архиве есть определённые свойства, например: имя файла, метод сжатия, метод шифрования, размер файла до сжатия, размер файла после сжатия, CRC32 и другие. -### Документация -#### Обзор методов класса `\PhpZip\ZipFile` -- [ZipFile::__construct](#Documentation-ZipFile-__construct) - инициализирует ZIP-архив. -- [ZipFile::addAll](#Documentation-ZipFile-addAll) - добавляет все записи из массива. -- [ZipFile::addDir](#Documentation-ZipFile-addDir) - добавляет файлы из директории по указанному пути без вложенных директорий. -- [ZipFile::addDirRecursive](#Documentation-ZipFile-addDirRecursive) - добавляет файлы из директории по указанному пути с вложенными директориями. -- [ZipFile::addEmptyDir](#Documentation-ZipFile-addEmptyDir) - добавляет в ZIP-архив новую директорию. -- [ZipFile::addFile](#Documentation-ZipFile-addFile) - добавляет в ZIP-архив файл по указанному пути. -- [ZipFile::addSplFile](#Documentation-ZipFile-addSplFile) - добавляет объект `\SplFileInfo` в zip-архив. -- [ZipFile::addFromFinder](#Documentation-ZipFile-addFromFinder) - добавляет файлы из `Symfony\Component\Finder\Finder` в zip архив. -- [ZipFile::addFilesFromIterator](#Documentation-ZipFile-addFilesFromIterator) - добавляет файлы из итератора директорий. -- [ZipFile::addFilesFromGlob](#Documentation-ZipFile-addFilesFromGlob) - добавляет файлы из директории в соответствии с glob шаблоном без вложенных директорий. -- [ZipFile::addFilesFromGlobRecursive](#Documentation-ZipFile-addFilesFromGlobRecursive) - добавляет файлы из директории в соответствии с glob шаблоном c вложенными директориями. -- [ZipFile::addFilesFromRegex](#Documentation-ZipFile-addFilesFromRegex) - добавляет файлы из директории в соответствии с регулярным выражением без вложенных директорий. -- [ZipFile::addFilesFromRegexRecursive](#Documentation-ZipFile-addFilesFromRegexRecursive) - добавляет файлы из директории в соответствии с регулярным выражением с вложенными директориями. -- [ZipFile::addFromStream](#Documentation-ZipFile-addFromStream) - добавляет в ZIP-архив запись из потока. -- [ZipFile::addFromString](#Documentation-ZipFile-addFromString) - добавляет файл в ZIP-архив, используя его содержимое в виде строки. -- [ZipFile::close](#Documentation-ZipFile-close) - закрывает ZIP-архив. -- [ZipFile::count](#Documentation-ZipFile-count) - возвращает количество записей в архиве. -- [ZipFile::deleteFromName](#Documentation-ZipFile-deleteFromName) - удаляет запись по имени. -- [ZipFile::deleteFromGlob](#Documentation-ZipFile-deleteFromGlob) - удаляет записи в соответствии с glob шаблоном. -- [ZipFile::deleteFromRegex](#Documentation-ZipFile-deleteFromRegex) - удаляет записи в соответствии с регулярным выражением. -- [ZipFile::deleteAll](#Documentation-ZipFile-deleteAll) - удаляет все записи в ZIP-архиве. -- [ZipFile::disableEncryption](#Documentation-ZipFile-disableEncryption) - отключает шифрования всех записей, находящихся в архиве. -- [ZipFile::disableEncryptionEntry](#Documentation-ZipFile-disableEncryptionEntry) - отключает шифрование записи по её имени. -- [ZipFile::extractTo](#Documentation-ZipFile-extractTo) - извлекает содержимое архива в заданную директорию. -- [ZipFile::getArchiveComment](#Documentation-ZipFile-getArchiveComment) - возвращает комментарий ZIP-архива. -- [ZipFile::getEntryComment](#Documentation-ZipFile-getEntryComment) - возвращает комментарий к записи, используя её имя. -- [ZipFile::getEntryContent](#Documentation-ZipFile-getEntryContent) - возвращает содержимое записи. -- [ZipFile::getListFiles](#Documentation-ZipFile-getListFiles) - возвращает список файлов архива. -- [ZipFile::hasEntry](#Documentation-ZipFile-hasEntry) - проверяет, присутствует ли запись в архиве. -- [ZipFile::isDirectory](#Documentation-ZipFile-isDirectory) - проверяет, является ли запись в архиве директорией. -- [ZipFile::matcher](#Documentation-ZipFile-matcher) - выборка записей в архиве для проведения операций над выбранными записями. -- [ZipFile::openFile](#Documentation-ZipFile-openFile) - открывает ZIP-архив из файла. -- [ZipFile::openFromString](#Documentation-ZipFile-openFromString) - открывает ZIP-архив из строки. -- [ZipFile::openFromStream](#Documentation-ZipFile-openFromStream) - открывает ZIP-архив из потока. -- [ZipFile::outputAsAttachment](#Documentation-ZipFile-outputAsAttachment) - выводит ZIP-архив в браузер. -- [ZipFile::outputAsResponse](#Documentation-ZipFile-outputAsResponse) - выводит ZIP-архив, как Response PSR-7. -- [ZipFile::outputAsString](#Documentation-ZipFile-outputAsString) - выводит ZIP-архив в виде строки. -- [ZipFile::rename](#Documentation-ZipFile-rename) - переименовывает запись по имени. -- [ZipFile::rewrite](#Documentation-ZipFile-rewrite) - сохраняет изменения и заново открывает изменившийся архив. -- [ZipFile::saveAsFile](#Documentation-ZipFile-saveAsFile) - сохраняет архив в файл. -- [ZipFile::saveAsStream](#Documentation-ZipFile-saveAsStream) - записывает архив в поток. -- [ZipFile::setArchiveComment](#Documentation-ZipFile-setArchiveComment) - устанавливает комментарий к ZIP-архиву. -- [ZipFile::setCompressionLevel](#Documentation-ZipFile-setCompressionLevel) - устанавливает уровень сжатия для всех файлов, находящихся в архиве. -- [ZipFile::setCompressionLevelEntry](#Documentation-ZipFile-setCompressionLevelEntry) - устанавливает уровень сжатия для определённой записи в архиве. -- [ZipFile::setCompressionMethodEntry](#Documentation-ZipFile-setCompressionMethodEntry) - устанавливает метод сжатия для определённой записи в архиве. -- [ZipFile::setEntryComment](#Documentation-ZipFile-setEntryComment) - устанавливает комментарий к записи, используя её имя. -- [ZipFile::setReadPassword](#Documentation-ZipFile-setReadPassword) - устанавливает пароль на чтение открытого запароленного архива для всех зашифрованных записей. -- [ZipFile::setReadPasswordEntry](#Documentation-ZipFile-setReadPasswordEntry) - устанавливает пароль на чтение конкретной зашифрованной записи открытого запароленного архива. -- [ZipFile::setPassword](#Documentation-ZipFile-setPassword) - устанавливает новый пароль для всех файлов, находящихся в архиве. -- [ZipFile::setPasswordEntry](#Documentation-ZipFile-setPasswordEntry) - устанавливает новый пароль для конкретного файла. -- [ZipFile::unchangeAll](#Documentation-ZipFile-unchangeAll) - отменяет все изменения, сделанные в архиве. -- [ZipFile::unchangeArchiveComment](#Documentation-ZipFile-unchangeArchiveComment) - отменяет изменения в комментарии к архиву. -- [ZipFile::unchangeEntry](#Documentation-ZipFile-unchangeEntry) - отменяет изменения для конкретной записи архива. +### Документация +#### Обзор методов класса `\PhpZip\ZipFile` +- [ZipFile::__construct](#zipfile__construct) - инициализирует ZIP-архив. +- [ZipFile::addAll](#zipfileaddall) - добавляет все записи из массива. +- [ZipFile::addDir](#zipfileadddir) - добавляет файлы из директории по указанному пути без вложенных директорий. +- [ZipFile::addDirRecursive](#zipfileadddirrecursive) - добавляет файлы из директории по указанному пути с вложенными директориями. +- [ZipFile::addEmptyDir](#zipfileaddemptydir) - добавляет в ZIP-архив новую директорию. +- [ZipFile::addFile](#zipfileaddfile) - добавляет в ZIP-архив файл по указанному пути. +- [ZipFile::addSplFile](#zipfileaddsplfile) - добавляет объект `\SplFileInfo` в zip-архив. +- [ZipFile::addFromFinder](#zipfileaddfromfinder) - добавляет файлы из `Symfony\Component\Finder\Finder` в zip архив. +- [ZipFile::addFilesFromIterator](#zipfileaddfilesfromiterator) - добавляет файлы из итератора директорий. +- [ZipFile::addFilesFromGlob](#zipfileaddfilesfromglob) - добавляет файлы из директории в соответствии с glob шаблоном без вложенных директорий. +- [ZipFile::addFilesFromGlobRecursive](#zipfileaddfilesfromglobrecursive) - добавляет файлы из директории в соответствии с glob шаблоном c вложенными директориями. +- [ZipFile::addFilesFromRegex](#zipfileaddfilesfromregex) - добавляет файлы из директории в соответствии с регулярным выражением без вложенных директорий. +- [ZipFile::addFilesFromRegexRecursive](#zipfileaddfilesfromregexrecursive) - добавляет файлы из директории в соответствии с регулярным выражением с вложенными директориями. +- [ZipFile::addFromStream](#zipfileaddfromstream) - добавляет в ZIP-архив запись из потока. +- [ZipFile::addFromString](#zipfileaddfromstring) - добавляет файл в ZIP-архив, используя его содержимое в виде строки. +- [ZipFile::close](#zipfileclose) - закрывает ZIP-архив. +- [ZipFile::count](#zipfilecount) - возвращает количество записей в архиве. +- [ZipFile::deleteFromName](#zipfiledeletefromname) - удаляет запись по имени. +- [ZipFile::deleteFromGlob](#zipfiledeletefromglob) - удаляет записи в соответствии с glob шаблоном. +- [ZipFile::deleteFromRegex](#zipfiledeletefromregex) - удаляет записи в соответствии с регулярным выражением. +- [ZipFile::deleteAll](#zipfiledeleteall) - удаляет все записи в ZIP-архиве. +- [ZipFile::disableEncryption](#zipfiledisableencryption) - отключает шифрования всех записей, находящихся в архиве. +- [ZipFile::disableEncryptionEntry](#zipfiledisableencryptionentry) - отключает шифрование записи по её имени. +- [ZipFile::extractTo](#zipfileextractto) - извлекает содержимое архива в заданную директорию. +- [ZipFile::getArchiveComment](#zipfilegetarchivecomment) - возвращает комментарий ZIP-архива. +- [ZipFile::getEntryComment](#zipfilegetentrycomment) - возвращает комментарий к записи, используя её имя. +- [ZipFile::getEntryContent](#zipfilegetentrycontent) - возвращает содержимое записи. +- [ZipFile::getListFiles](#zipfilegetlistfiles) - возвращает список файлов архива. +- [ZipFile::hasEntry](#zipfilehasentry) - проверяет, присутствует ли запись в архиве. +- [ZipFile::isDirectory](#zipfileisdirectory) - проверяет, является ли запись в архиве директорией. +- [ZipFile::matcher](#zipfilematcher) - выборка записей в архиве для проведения операций над выбранными записями. +- [ZipFile::openFile](#zipfileopenfile) - открывает ZIP-архив из файла. +- [ZipFile::openFromString](#zipfileopenfromstring) - открывает ZIP-архив из строки. +- [ZipFile::openFromStream](#zipfileopenfromstream) - открывает ZIP-архив из потока. +- [ZipFile::outputAsAttachment](#zipfileoutputasattachment) - выводит ZIP-архив в браузер. +- [ZipFile::outputAsResponse](#zipfileoutputasresponse) - выводит ZIP-архив, как Response PSR-7. +- [ZipFile::outputAsString](#zipfileoutputasstring) - выводит ZIP-архив в виде строки. +- [ZipFile::rename](#zipfilerename) - переименовывает запись по имени. +- [ZipFile::rewrite](#zipfilerewrite) - сохраняет изменения и заново открывает изменившийся архив. +- [ZipFile::saveAsFile](#zipfilesaveasfile) - сохраняет архив в файл. +- [ZipFile::saveAsStream](#zipfilesaveasstream) - записывает архив в поток. +- [ZipFile::setArchiveComment](#zipfilesetarchivecomment) - устанавливает комментарий к ZIP-архиву. +- [ZipFile::setCompressionLevel](#zipfilesetcompressionlevel) - устанавливает уровень сжатия для всех файлов, находящихся в архиве. +- [ZipFile::setCompressionLevelEntry](#zipfilesetcompressionlevelentry) - устанавливает уровень сжатия для определённой записи в архиве. +- [ZipFile::setCompressionMethodEntry](#zipfilesetcompressionmethodentry) - устанавливает метод сжатия для определённой записи в архиве. +- [ZipFile::setEntryComment](#zipfilesetentrycomment) - устанавливает комментарий к записи, используя её имя. +- [ZipFile::setReadPassword](#zipfilesetreadpassword) - устанавливает пароль на чтение открытого запароленного архива для всех зашифрованных записей. +- [ZipFile::setReadPasswordEntry](#zipfilesetreadpasswordentry) - устанавливает пароль на чтение конкретной зашифрованной записи открытого запароленного архива. +- [ZipFile::setPassword](#zipfilesetpassword) - устанавливает новый пароль для всех файлов, находящихся в архиве. +- [ZipFile::setPasswordEntry](#zipfilesetpasswordentry) - устанавливает новый пароль для конкретного файла. +- [ZipFile::unchangeAll](#zipfileunchangeall) - отменяет все изменения, сделанные в архиве. +- [ZipFile::unchangeArchiveComment](#zipfileunchangearchivecomment) - отменяет изменения в комментарии к архиву. +- [ZipFile::unchangeEntry](#zipfileunchangeentry) - отменяет изменения для конкретной записи архива. -#### Создание/Открытие ZIP-архива -**ZipFile::__construct** - Инициализацирует ZIP-архив. +#### Создание/Открытие ZIP-архива +##### ZipFile::__construct +Инициализирует ZIP-архив. ```php $zipFile = new \PhpZip\ZipFile(); ``` - **ZipFile::openFile** - открывает ZIP-архив из файла. +##### ZipFile::openFile +Открывает ZIP-архив из файла. ```php $zipFile = new \PhpZip\ZipFile(); $zipFile->openFile('file.zip'); ``` - **ZipFile::openFromString** - открывает ZIP-архив из строки. +##### ZipFile::openFromString +Открывает ZIP-архив из строки. ```php $zipFile = new \PhpZip\ZipFile(); $zipFile->openFromString($stringContents); ``` - **ZipFile::openFromStream** - открывает ZIP-архив из потока. +##### ZipFile::openFromStream +Открывает ZIP-архив из потока. ```php $stream = fopen('file.zip', 'rb'); $zipFile = new \PhpZip\ZipFile(); $zipFile->openFromStream($stream); ``` -#### Чтение записей из архива - **ZipFile::count** - возвращает количество записей в архиве. +#### Чтение записей из архива +##### ZipFile::count +Возвращает количество записей в архиве. ```php $zipFile = new \PhpZip\ZipFile(); @@ -193,7 +199,8 @@ $count = count($zipFile); // или $count = $zipFile->count(); ``` - **ZipFile::getListFiles** - возвращает список файлов архива. +##### ZipFile::getListFiles +Возвращает список файлов архива. ```php $zipFile = new \PhpZip\ZipFile(); $listFiles = $zipFile->getListFiles(); @@ -205,7 +212,8 @@ $listFiles = $zipFile->getListFiles(); // 2 => 'another path/', // ) ``` - **ZipFile::getEntryContent** - возвращает содержимое записи. +##### ZipFile::getEntryContent +Возвращает содержимое записи. ```php // $entryName = 'path/to/example-entry-name.txt'; $zipFile = new \PhpZip\ZipFile(); @@ -214,7 +222,8 @@ $contents = $zipFile[$entryName]; // или $contents = $zipFile->getEntryContents($entryName); ``` - **ZipFile::hasEntry** - проверяет, присутствует ли запись в архиве. +##### ZipFile::hasEntry +Проверяет, присутствует ли запись в архиве. ```php // $entryName = 'path/to/example-entry-name.txt'; $zipFile = new \PhpZip\ZipFile(); @@ -223,14 +232,16 @@ $hasEntry = isset($zipFile[$entryName]); // или $hasEntry = $zipFile->hasEntry($entryName); ``` - **ZipFile::isDirectory** - проверяет, является ли запись в архиве директорией. +##### ZipFile::isDirectory +Проверяет, является ли запись в архиве директорией. ```php // $entryName = 'path/to/'; $zipFile = new \PhpZip\ZipFile(); $isDirectory = $zipFile->isDirectory($entryName); ``` - **ZipFile::extractTo** - извлекает содержимое архива в заданную директорию. +##### ZipFile::extractTo +Извлекает содержимое архива в заданную директорию. Директория должна существовать. ```php $zipFile = new \PhpZip\ZipFile(); @@ -247,7 +258,7 @@ $extractOnlyFiles = [ $zipFile = new \PhpZip\ZipFile(); $zipFile->extractTo($toDirectory, $extractOnlyFiles); ``` -#### Перебор записей/Итератор +#### Перебор записей/Итератор `ZipFile` является итератором. Можно перебрать все записи, через цикл `foreach`. ```php @@ -272,16 +283,18 @@ while ($iterator->valid()) $iterator->next(); } ``` -#### Получение информации о записях - **ZipFile::getArchiveComment** - возвращает комментарий ZIP-архива. +#### Получение информации о записях +##### ZipFile::getArchiveComment +Возвращает комментарий ZIP-архива. ```php $commentArchive = $zipFile->getArchiveComment(); ``` - **ZipFile::getEntryComment** - возвращает комментарий к записи, используя её имя. +##### ZipFile::getEntryComment +Возвращает комментарий к записи, используя её имя. ```php $commentEntry = $zipFile->getEntryComment($entryName); ``` -#### Добавление записей в архив +#### Добавление записей в архив Все методы добавления записей в ZIP-архив позволяют указать метод сжатия содержимого. @@ -290,7 +303,8 @@ $commentEntry = $zipFile->getEntryComment($entryName); - `\PhpZip\Constants\ZipCompressionMethod::DEFLATED` - Deflate сжатие - `\PhpZip\Constants\ZipCompressionMethod::BZIP2` - Bzip2 сжатие при наличии расширения `ext-bz2` - **ZipFile::addFile** - добавляет в ZIP-архив файл по указанному пути из файловой системы. +##### ZipFile::addFile +Добавляет в ZIP-архив файл по указанному пути из файловой системы. ```php $zipFile = new \PhpZip\ZipFile(); // $file = '...../file.ext'; @@ -304,8 +318,8 @@ $zipFile->addFile($file, $entryName, \PhpZip\Constants\ZipCompressionMethod::STO $zipFile->addFile($file, $entryName, \PhpZip\Constants\ZipCompressionMethod::DEFLATED); // Deflate сжатие $zipFile->addFile($file, $entryName, \PhpZip\Constants\ZipCompressionMethod::BZIP2); // BZIP2 сжатие ``` - -**ZipFile::addSplFile"** - добавляет объект `\SplFileInfo` в zip-архив. +##### ZipFile::addSplFile" +Добавляет объект `\SplFileInfo` в zip-архив. ```php // $file = '...../file.ext'; // $entryName = 'file2.ext' @@ -323,9 +337,8 @@ $zipFile->addSplFile($splFile, $entryName, $options = [ \PhpZip\Constants\ZipOptions::COMPRESSION_METHOD => \PhpZip\Constants\ZipCompressionMethod::DEFLATED, ]); ``` - -**ZipFile::addFromFinder"** - добавляет файлы из `Symfony\Component\Finder\Finder` в zip архив. -https://symfony.com/doc/current/components/finder.html +##### ZipFile::addFromFinder" +Добавляет файлы из [`Symfony\Component\Finder\Finder`](https://symfony.com/doc/current/components/finder.html) в zip архив. ```php $finder = new \Symfony\Component\Finder\Finder(); $finder @@ -341,7 +354,8 @@ $zipFile->addFromFinder($finder, $options = [ \PhpZip\Constants\ZipOptions::MODIFIED_TIME => new \DateTimeImmutable('-1 day 5 min') ]); ``` - **ZipFile::addFromString** - добавляет файл в ZIP-архив, используя его содержимое в виде строки. +##### ZipFile::addFromString +Добавляет файл в ZIP-архив, используя его содержимое в виде строки. ```php $zipFile = new \PhpZip\ZipFile(); @@ -354,7 +368,8 @@ $zipFile->addFromString($entryName, $contents, \PhpZip\Constants\ZipCompressionM $zipFile->addFromString($entryName, $contents, \PhpZip\Constants\ZipCompressionMethod::DEFLATED); // Deflate сжатие $zipFile->addFromString($entryName, $contents, \PhpZip\Constants\ZipCompressionMethod::BZIP2); // BZIP2 сжатие ``` - **ZipFile::addFromStream** - добавляет в ZIP-архив запись из потока. +##### ZipFile::addFromStream +Добавляет в ZIP-архив запись из потока. ```php // $stream = fopen(..., 'rb'); @@ -365,7 +380,8 @@ $zipFile->addFromStream($stream, $entryName, \PhpZip\Constants\ZipCompressionMet $zipFile->addFromStream($stream, $entryName, \PhpZip\Constants\ZipCompressionMethod::DEFLATED); // Deflate сжатие $zipFile->addFromStream($stream, $entryName, \PhpZip\Constants\ZipCompressionMethod::BZIP2); // BZIP2 сжатие ``` - **ZipFile::addEmptyDir** - добавляет в ZIP-архив новую (пустую) директорию. +##### ZipFile::addEmptyDir +Добавляет в ZIP-архив новую (пустую) директорию. ```php // $path = "path/to/"; @@ -373,7 +389,8 @@ $zipFile->addEmptyDir($path); // или $zipFile[$path] = null; ``` - **ZipFile::addAll** - добавляет все записи из массива. +##### ZipFile::addAll +Добавляет все записи из массива. ```php $entries = [ 'file.txt' => 'file contents', // запись из строки данных @@ -384,7 +401,8 @@ $entries = [ $zipFile->addAll($entries); ``` - **ZipFile::addDir** - добавляет файлы из директории по указанному пути без вложенных директорий. +##### ZipFile::addDir +Добавляет файлы из директории по указанному пути без вложенных директорий. ```php $zipFile->addDir($dirName); @@ -397,7 +415,8 @@ $zipFile->addDir($dirName, $localPath, \PhpZip\Constants\ZipCompressionMethod::S $zipFile->addDir($dirName, $localPath, \PhpZip\Constants\ZipCompressionMethod::DEFLATED); // Deflate сжатие $zipFile->addDir($dirName, $localPath, \PhpZip\Constants\ZipCompressionMethod::BZIP2); // BZIP2 сжатие ``` - **ZipFile::addDirRecursive** - добавляет файлы из директории по указанному пути c вложенными директориями. +##### ZipFile::addDirRecursive +Добавляет файлы из директории по указанному пути c вложенными директориями. ```php $zipFile->addDirRecursive($dirName); @@ -410,7 +429,8 @@ $zipFile->addDirRecursive($dirName, $localPath, \PhpZip\Constants\ZipCompression $zipFile->addDirRecursive($dirName, $localPath, \PhpZip\Constants\ZipCompressionMethod::DEFLATED); // Deflate сжатие $zipFile->addDirRecursive($dirName, $localPath, \PhpZip\Constants\ZipCompressionMethod::BZIP2); // BZIP2 сжатие ``` - **ZipFile::addFilesFromIterator** - добавляет файлы из итератора директорий. +##### ZipFile::addFilesFromIterator +Добавляет файлы из итератора директорий. ```php // $directoryIterator = new \DirectoryIterator($dir); // без вложенных директорий // $directoryIterator = new \RecursiveDirectoryIterator($dir); // с вложенными директориями @@ -446,7 +466,8 @@ $ignoreIterator = new \PhpZip\Util\Iterator\IgnoreFilesRecursiveFilterIterator( $zipFile->addFilesFromIterator($ignoreIterator); ``` - **ZipFile::addFilesFromGlob** - добавляет файлы из директории в соответствии с [glob шаблоном](https://en.wikipedia.org/wiki/Glob_(programming)) без вложенных директорий. +##### ZipFile::addFilesFromGlob +Добавляет файлы из директории в соответствии с [glob шаблоном](https://en.wikipedia.org/wiki/Glob_(programming)) без вложенных директорий. ```php $globPattern = '**.{jpg,jpeg,png,gif}'; // пример glob шаблона -> добавить все .jpg, .jpeg, .png и .gif файлы @@ -461,7 +482,8 @@ $zipFile->addFilesFromGlob($dir, $globPattern, $localPath, \PhpZip\Constants\Zip $zipFile->addFilesFromGlob($dir, $globPattern, $localPath, \PhpZip\Constants\ZipCompressionMethod::DEFLATED); // Deflate сжатие $zipFile->addFilesFromGlob($dir, $globPattern, $localPath, \PhpZip\Constants\ZipCompressionMethod::BZIP2); // BZIP2 сжатие ``` - **ZipFile::addFilesFromGlobRecursive** - добавляет файлы из директории в соответствии с [glob шаблоном](https://en.wikipedia.org/wiki/Glob_(programming)) c вложенными директориями. +##### ZipFile::addFilesFromGlobRecursive +Добавляет файлы из директории в соответствии с [glob шаблоном](https://en.wikipedia.org/wiki/Glob_(programming)) c вложенными директориями. ```php $globPattern = '**.{jpg,jpeg,png,gif}'; // пример glob шаблона -> добавить все .jpg, .jpeg, .png и .gif файлы @@ -476,7 +498,8 @@ $zipFile->addFilesFromGlobRecursive($dir, $globPattern, $localPath, \PhpZip\Cons $zipFile->addFilesFromGlobRecursive($dir, $globPattern, $localPath, \PhpZip\Constants\ZipCompressionMethod::DEFLATED); // Deflate сжатие $zipFile->addFilesFromGlobRecursive($dir, $globPattern, $localPath, \PhpZip\Constants\ZipCompressionMethod::BZIP2); // BZIP2 сжатие ``` - **ZipFile::addFilesFromRegex** - добавляет файлы из директории в соответствии с [регулярным выражением](https://en.wikipedia.org/wiki/Regular_expression) без вложенных директорий. +##### ZipFile::addFilesFromRegex +Добавляет файлы из директории в соответствии с [регулярным выражением](https://en.wikipedia.org/wiki/Regular_expression) без вложенных директорий. ```php $regexPattern = '/\.(jpe?g|png|gif)$/si'; // пример регулярного выражения -> добавить все .jpg, .jpeg, .png и .gif файлы @@ -491,7 +514,8 @@ $zipFile->addFilesFromRegex($dir, $regexPattern, $localPath, \PhpZip\Constants\Z $zipFile->addFilesFromRegex($dir, $regexPattern, $localPath, \PhpZip\Constants\ZipCompressionMethod::DEFLATED); // Deflate сжатие $zipFile->addFilesFromRegex($dir, $regexPattern, $localPath, \PhpZip\Constants\ZipCompressionMethod::BZIP2); // BZIP2 сжатие ``` - **ZipFile::addFilesFromRegexRecursive** - добавляет файлы из директории в соответствии с [регулярным выражением](https://en.wikipedia.org/wiki/Regular_expression) с вложенными директориями. +##### ZipFile::addFilesFromRegexRecursive +Добавляет файлы из директории в соответствии с [регулярным выражением](https://en.wikipedia.org/wiki/Regular_expression) с вложенными директориями. ```php $regexPattern = '/\.(jpe?g|png|gif)$/si'; // пример регулярного выражения -> добавить все .jpg, .jpeg, .png и .gif файлы @@ -506,33 +530,39 @@ $zipFile->addFilesFromRegexRecursive($dir, $regexPattern, $localPath, \PhpZip\Co $zipFile->addFilesFromRegexRecursive($dir, $regexPattern, $localPath, \PhpZip\Constants\ZipCompressionMethod::DEFLATED); // Deflate сжатие $zipFile->addFilesFromRegexRecursive($dir, $regexPattern, $localPath, \PhpZip\Constants\ZipCompressionMethod::BZIP2); // BZIP2 сжатие ``` -#### Удаление записей из архива - **ZipFile::deleteFromName** - удаляет запись по имени. +#### Удаление записей из архива +##### ZipFile::deleteFromName +Удаляет запись по имени. ```php $zipFile->deleteFromName($entryName); ``` - **ZipFile::deleteFromGlob** - удаляет записи в соответствии с [glob шаблоном](https://en.wikipedia.org/wiki/Glob_(programming)). +##### ZipFile::deleteFromGlob +Удаляет записи в соответствии с [glob шаблоном](https://en.wikipedia.org/wiki/Glob_(programming)). ```php $globPattern = '**.{jpg,jpeg,png,gif}'; // пример glob шаблона -> удалить все .jpg, .jpeg, .png и .gif файлы $zipFile->deleteFromGlob($globPattern); ``` - **ZipFile::deleteFromRegex** - удаляет записи в соответствии с [регулярным выражением](https://en.wikipedia.org/wiki/Regular_expression). +##### ZipFile::deleteFromRegex +Удаляет записи в соответствии с [регулярным выражением](https://en.wikipedia.org/wiki/Regular_expression). ```php $regexPattern = '/\.(jpe?g|png|gif)$/si'; // пример регулярному выражения -> удалить все .jpg, .jpeg, .png и .gif файлы $zipFile->deleteFromRegex($regexPattern); ``` - **ZipFile::deleteAll** - удаляет все записи в ZIP-архиве. +##### ZipFile::deleteAll +Удаляет все записи в ZIP-архиве. ```php $zipFile->deleteAll(); ``` -#### Работа с записями и с архивом - **ZipFile::rename** - переименовывает запись по имени. +#### Работа с записями и с архивом +##### ZipFile::rename +Переименовывает запись по имени. ```php $zipFile->rename($oldName, $newName); ``` - **ZipFile::setCompressionLevel** - устанавливает уровень сжатия для всех файлов, находящихся в архиве. +##### ZipFile::setCompressionLevel +Устанавливает уровень сжатия для всех файлов, находящихся в архиве. > _Обратите внимание, что действие данного метода не распространяется на записи, добавленные после выполнения этого метода._ @@ -542,13 +572,15 @@ $zipFile->rename($oldName, $newName); ```php $zipFile->setCompressionLevel(\PhpZip\Constants\ZipCompressionLevel::MAXIMUM); ``` - **ZipFile::setCompressionLevelEntry** - устанавливает уровень сжатия для определённой записи в архиве. +##### ZipFile::setCompressionLevelEntry +Устанавливает уровень сжатия для определённой записи в архиве. Поддерживаются диапазон значений от 1 (`\PhpZip\Constants\ZipCompressionLevel::SUPER_FAST`) до 9 (`\PhpZip\Constants\ZipCompressionLevel::MAXIMUM`). Чем выше число, тем лучше и дольше сжатие. ```php $zipFile->setCompressionLevelEntry($entryName, \PhpZip\Constants\ZipCompressionLevel::MAXIMUM); ``` - **ZipFile::setCompressionMethodEntry** - устанавливает метод сжатия для определённой записи в архиве. +##### ZipFile::setCompressionMethodEntry +Устанавливает метод сжатия для определённой записи в архиве. Доступны следующие методы сжатия: - `\PhpZip\Constants\ZipCompressionMethod::STORED` - без сжатия @@ -557,15 +589,18 @@ $zipFile->setCompressionLevelEntry($entryName, \PhpZip\Constants\ZipCompressionL ```php $zipFile->setCompressionMethodEntry($entryName, \PhpZip\Constants\ZipCompressionMethod::DEFLATED); ``` - **ZipFile::setArchiveComment** - устанавливает комментарий к ZIP-архиву. +##### ZipFile::setArchiveComment +Устанавливает комментарий к ZIP-архиву. ```php $zipFile->setArchiveComment($commentArchive); ``` - **ZipFile::setEntryComment** - устанавливает комментарий к записи, используя её имя. +##### ZipFile::setEntryComment +Устанавливает комментарий к записи, используя её имя. ```php $zipFile->setEntryComment($entryName, $comment); ``` - **ZipFile::matcher** - выборка записей в архиве для проведения операций над выбранными записями. +##### ZipFile::matcher +Выборка записей в архиве для проведения операций над выбранными записями. ```php $matcher = $zipFile->matcher(); ``` @@ -618,7 +653,7 @@ $matcher->setPassword($password, $encryptionMethod); // устанавливае $matcher->setEncryptionMethod($encryptionMethod); // устанавливает метод шифрования на выбранные записи $matcher->disableEncryption(); // отключает шифрование для выбранных записей ``` -#### Работа с паролями +#### Работа с паролями Реализована поддержка методов шифрования: - `\PhpZip\Constants\ZipEncryptionMethod::PKWARE` - Traditional PKWARE encryption @@ -626,17 +661,20 @@ $matcher->disableEncryption(); // отключает шифрование для - `\PhpZip\Constants\ZipEncryptionMethod::WINZIP_AES_192` - WinZip AES encryption 192 bit - `\PhpZip\Constants\ZipEncryptionMethod::WINZIP_AES_128` - WinZip AES encryption 128 bit - **ZipFile::setReadPassword** - устанавливает пароль на чтение открытого запароленного архива для всех зашифрованных записей. +##### ZipFile::setReadPassword +Устанавливает пароль на чтение открытого запароленного архива для всех зашифрованных записей. > _Установка пароля не является обязательной для добавления новых записей или удаления существующих, но если вы захотите извлечь контент или изменить метод/уровень сжатия, метод шифрования или изменить пароль, то в этом случае пароль необходимо указать._ ```php $zipFile->setReadPassword($password); ``` - **ZipFile::setReadPasswordEntry** - устанавливает пароль на чтение конкретной зашифрованной записи открытого запароленного архива. +##### ZipFile::setReadPasswordEntry +Устанавливает пароль на чтение конкретной зашифрованной записи открытого запароленного архива. ```php $zipFile->setReadPasswordEntry($entryName, $password); ``` - **ZipFile::setPassword** - устанавливает новый пароль для всех файлов, находящихся в архиве. +##### ZipFile::setPassword +Устанавливает новый пароль для всех файлов, находящихся в архиве. > _Обратите внимание, что действие данного метода не распространяется на записи, добавленные после выполнения этого метода._ ```php @@ -647,7 +685,8 @@ $zipFile->setPassword($password); $encryptionMethod = \PhpZip\Constants\ZipEncryptionMethod::WINZIP_AES_256; $zipFile->setPassword($password, $encryptionMethod); ``` - **ZipFile::setPasswordEntry** - устанавливает новый пароль для конкретного файла. +##### ZipFile::setPasswordEntry +Устанавливает новый пароль для конкретного файла. ```php $zipFile->setPasswordEntry($entryName, $password); ``` @@ -656,45 +695,54 @@ $zipFile->setPasswordEntry($entryName, $password); $encryptionMethod = \PhpZip\Constants\ZipEncryptionMethod::WINZIP_AES_256; $zipFile->setPasswordEntry($entryName, $password, $encryptionMethod); ``` - **ZipFile::disableEncryption** - отключает шифрования всех записей, находящихся в архиве. +##### ZipFile::disableEncryption +Отключает шифрования всех записей, находящихся в архиве. > _Обратите внимание, что действие данного метода не распространяется на записи, добавленные после выполнения этого метода._ ```php $zipFile->disableEncryption(); ``` - **ZipFile::disableEncryptionEntry** - отключает шифрование записи по её имени. +##### ZipFile::disableEncryptionEntry +Отключает шифрование записи по её имени. ```php $zipFile->disableEncryptionEntry($entryName); ``` -#### Отмена изменений - **ZipFile::unchangeAll** - отменяет все изменения, сделанные в архиве. +#### Отмена изменений +##### ZipFile::unchangeAll +Отменяет все изменения, сделанные в архиве. ```php $zipFile->unchangeAll(); ``` - **ZipFile::unchangeArchiveComment** - отменяет изменения в комментарии к архиву. +##### ZipFile::unchangeArchiveComment +Отменяет изменения в комментарии к архиву. ```php $zipFile->unchangeArchiveComment(); ``` - **ZipFile::unchangeEntry** - отменяет изменения для конкретной записи архива. +##### ZipFile::unchangeEntry +Отменяет изменения для конкретной записи архива. ```php $zipFile->unchangeEntry($entryName); ``` -#### Сохранение файла или вывод в браузер - **ZipFile::saveAsFile** - сохраняет архив в файл. +#### Сохранение файла или вывод в браузер +##### ZipFile::saveAsFile +Сохраняет архив в файл. ```php $zipFile->saveAsFile($filename); ``` - **ZipFile::saveAsStream** - записывает архив в поток. +##### ZipFile::saveAsStream +Записывает архив в поток. ```php // $fp = fopen($filename, 'w+b'); $zipFile->saveAsStream($fp); ``` - **ZipFile::outputAsString** - выводит ZIP-архив в виде строки. +##### ZipFile::outputAsString +Выводит ZIP-архив в виде строки. ```php $rawZipArchiveBytes = $zipFile->outputAsString(); ``` - **ZipFile::outputAsAttachment** - выводит ZIP-архив в браузер. +##### ZipFile::outputAsAttachment +Выводит ZIP-архив в браузер. При выводе устанавливаются необходимые заголовки, а после вывода завершается работа скрипта. ```php @@ -705,7 +753,8 @@ $zipFile->outputAsAttachment($outputFilename); $mimeType = 'application/zip'; $zipFile->outputAsAttachment($outputFilename, $mimeType); ``` - **ZipFile::outputAsResponse** - выводит ZIP-архив, как Response [PSR-7](http://www.php-fig.org/psr/psr-7/). +##### ZipFile::outputAsResponse +Выводит ZIP-архив, как Response [PSR-7](http://www.php-fig.org/psr/psr-7/). Метод вывода может использоваться в любом PSR-7 совместимом фреймворке. ```php @@ -727,16 +776,18 @@ $app->get('/download', function ($req, $res, $args) { }); $app->run(); ``` - **ZipFile::rewrite** - сохраняет изменения и заново открывает изменившийся архив. +##### ZipFile::rewrite +Сохраняет изменения и заново открывает изменившийся архив. ```php $zipFile->rewrite(); ``` -#### Закрытие архива - **ZipFile::close** - закрывает ZIP-архив. +#### Закрытие архива +##### ZipFile::close +Закрывает ZIP-архив. ```php $zipFile->close(); ``` -### Запуск тестов +### Запуск тестов Установите зависимости для разработки. ```bash composer install --dev @@ -745,11 +796,11 @@ composer install --dev ```bash vendor/bin/phpunit -v -c phpunit.xml ``` -### История изменений +### История изменений История изменений на [странице релизов](https://github.com/Ne-Lexa/php-zip/releases). -### Обновление версий -#### Обновление с версии 3 до версии 4 +### Обновление версий +#### Обновление с версии 3 до версии 4 Обновите мажорную версию в файле `composer.json` до `^4.0`. ```json { @@ -765,7 +816,7 @@ composer update nelexa/zip Обновите ваш код для работы с новой версией: - удалены устаревшие метроды - удалён zipalign функционал (он будет помещен в отдельный пакет nelexa/apkfile) -#### Обновление с версии 2 до версии 3.0 +#### Обновление с версии 2 до версии 3 Обновите мажорную версию в файле `composer.json` до `^3.0`. ```json { diff --git a/README.md b/README.md index dc45656..64a89c0 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,11 @@ `PhpZip` is a php-library for extended work with ZIP-archives. -[![Build Status](https://github.com/Ne-Lexa/php-zip/workflows/build/badge.svg)](https://github.com/Ne-Lexa/php-zip/actions) +[![Packagist Version](https://img.shields.io/packagist/v/nelexa/zip.svg)](https://packagist.org/packages/nelexa/zip) +[![Packagist Downloads](https://img.shields.io/packagist/dt/nelexa/zip.svg?color=%23ff007f)](https://packagist.org/packages/nelexa/zip) [![Code Coverage](https://scrutinizer-ci.com/g/Ne-Lexa/php-zip/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/Ne-Lexa/php-zip/?branch=master) -[![Latest Stable Version](https://poser.pugx.org/nelexa/zip/v/stable)](https://packagist.org/packages/nelexa/zip) -[![Total Downloads](https://poser.pugx.org/nelexa/zip/downloads)](https://packagist.org/packages/nelexa/zip) -[![License](https://poser.pugx.org/nelexa/zip/license)](https://packagist.org/packages/nelexa/zip) +[![Build Status](https://github.com/Ne-Lexa/php-zip/workflows/build/badge.svg)](https://github.com/Ne-Lexa/php-zip/actions) +[![License](https://img.shields.io/packagist/l/nelexa/zip.svg)](https://github.com/Ne-Lexa/php-zip/blob/master/LICENSE) [Russian Documentation](README.RU.md)