mirror/php-zip
1
0
Fork 0
mirror of https://github.com/Ne-Lexa/php-zip.git synced 2025-03-14 11:39:42 +01:00
Code Issues Releases Wiki Activity

README update

Browse Source
This commit is contained in:
Ne-Lexa 2017-03-13 19:59:30 +03:00
parent 1e4b14177a
commit 0dbdc0faeb
1 changed files with 178 additions and 146 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

324
README.md
View File

@ -4,10 +4,22 @@
[![Latest Stable Version](https://poser.pugx.org/nelexa/zip/v/stable)](https://packagist.org/packages/nelexa/zip) [![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) [![Total Downloads](https://poser.pugx.org/nelexa/zip/downloads)](https://packagist.org/packages/nelexa/zip)
[![Minimum PHP Version](http://img.shields.io/badge/php-%3E%3D%205.5-8892BF.svg)](https://php.net/)
[![Test Coverage](https://codeclimate.com/github/Ne-Lexa/php-zip/badges/coverage.svg)](https://codeclimate.com/github/Ne-Lexa/php-zip/coverage)
[![License](https://poser.pugx.org/nelexa/zip/license)](https://packagist.org/packages/nelexa/zip) [![License](https://poser.pugx.org/nelexa/zip/license)](https://packagist.org/packages/nelexa/zip)
Features: Table of contents
--------- -----------------
- [Features](#Features)
- [Requirements](#Requirements)
- [Installation](#Installation)
- [Examples](#Examples)
- [Documentation](#Documentation)
+ [Open Zip Archive](#Documentation-Open-Zip-Archive)
+ [Get Zip Entries](#Documentation-Open-Zip-Entries)
+ [Add Zip Entries](#Documentation-Add-Zip-Entries)
### <a name="Features"></a> Features
- Opening and unzipping zip files. - Opening and unzipping zip files.
- Create zip files. - Create zip files.
- Update zip files. - Update zip files.
@ -20,42 +32,38 @@ Features:
- Support `ZIP64` (size > 4 GiB or files > 65535 in a .ZIP archive). - Support `ZIP64` (size > 4 GiB or files > 65535 in a .ZIP archive).
- Support archive alignment functional [`zipalign`](https://developer.android.com/studio/command-line/zipalign.html). - Support archive alignment functional [`zipalign`](https://developer.android.com/studio/command-line/zipalign.html).
Requirements ### <a name="Requirements"></a> Requirements
------------
- `PHP` >= 5.5 (64 bit) - `PHP` >= 5.5 (64 bit)
- Optional php-extension `bzip2` for BZIP2 compression. - Optional php-extension `bzip2` for BZIP2 compression.
- Optional php-extension `openssl` or `mcrypt` for `WinZip Aes Encryption` support. - Optional php-extension `openssl` or `mcrypt` for `WinZip Aes Encryption` support.
Installation ### <a name="Installation"></a> Installation
------------
`composer require nelexa/zip:^3.0` `composer require nelexa/zip:^3.0`
Samples ### <a name="Examples"></a> Examples
-------
```php ```php
// create archive // create new archive
$zipFile = new \PhpZip\ZipFile(); $zipFile = new \PhpZip\ZipFile();
$zipFile->addFromString("zip/entry/filename", "Is file content") $zipFile
->addFile("/path/to/file", "data/tofile") ->addFromString("zip/entry/filename", "Is file content")
->addDir(__DIR__, "to/path/") ->addFile("/path/to/file", "data/tofile")
->saveAsFile($outputFilename) ->addDir(__DIR__, "to/path/")
->close(); ->saveAsFile($outputFilename)
->close();
// open archive, extract, add files, set password and output to browser. // open archive, extract, add files, set password and output to browser.
$zipFile->openFile($outputFilename) $zipFile
->extractTo($outputDirExtract) ->openFile($outputFilename)
->deleteFromRegex('~^\.~') // delete all hidden (Unix) files ->extractTo($outputDirExtract)
->addFromString('dir/file.txt', 'Test file') ->deleteFromRegex('~^\.~') // delete all hidden (Unix) files
->withNewPassword('password') ->addFromString('dir/file.txt', 'Test file')
->outputAsAttachment('library.jar'); ->withNewPassword('password')
->outputAsAttachment('library.jar');
``` ```
Other examples can be found in the `tests/` folder Other examples can be found in the `tests/` folder
Documentation ### <a name="Documentation"></a> Documentation
------------- ###### <a name="Documentation-Open-Zip-Archive"></a> Open Zip Archive
Open zip archive from file. Open zip archive from file.
```php ```php
$zipFile = new \PhpZip\ZipFile(); $zipFile = new \PhpZip\ZipFile();
@ -63,26 +71,67 @@ $zipFile->openFile($filename);
``` ```
Open zip archive from data string. Open zip archive from data string.
```php ```php
$data = file_get_contents($urlOrFile);
$zipFile = new \PhpZip\ZipFile(); $zipFile = new \PhpZip\ZipFile();
$zipFile->openFromString($filename); $zipFile->openFromString($stringContents);
``` ```
Open zip archive from stream resource. Open zip archive from stream resource.
```php ```php
$stream = fopen($filename, 'rb'); $stream = fopen($filename, 'rb');
$zipFile = \PhpZip\ZipFile::openFromStream($stream);
$zipFile = new \PhpZip\ZipFile();
$zipFile->openFromStream($stream);
###### <a name="Documentation-Open-Zip-Entries"></a> Get Zip Entries
``` ```
Get num entries. Get num entries.
```php ```php
$count = $zipFile->count();
// or
$count = count($zipFile); $count = count($zipFile);
// or
$count = $zipFile->count();
``` ```
Get list files. Get list files.
```php ```php
$listFiles = $zipFile->getListFiles(); $listFiles = $zipFile->getListFiles();
// Example result:
//
// $listFiles = [
// 'info.txt',
// 'path/to/file.jpg',
// 'another path/'
// ];
``` ```
Foreach zip entries. Get entry contents.
```php
// $entryName = 'path/to/example-entry-name.txt';
$contents = $zipFile[$entryName];
```
Checks whether a entry exists.
```php
// $entryName = 'path/to/example-entry-name.txt';
$hasEntry = isset($zipFile[$entryName]);
```
Check whether the directory entry.
```php
// $entryName = 'path/to/';
$isDirectory = $zipFile->isDirectory($entryName);
```
Extract all files to directory.
```php
$zipFile->extractTo($directory);
```
Extract some files to directory.
```php
$extractOnlyFiles = [
"filename1",
"filename2",
"dir/dir/dir/"
];
$zipFile->extractTo($directory, $extractOnlyFiles);
```
Iterate zip entries.
```php ```php
foreach($zipFile as $entryName => $dataContent){ foreach($zipFile as $entryName => $dataContent){
echo "Entry: $entryName" . PHP_EOL; echo "Entry: $entryName" . PHP_EOL;
@ -90,7 +139,7 @@ foreach($zipFile as $entryName => $dataContent){
echo "-----------------------------" . PHP_EOL; echo "-----------------------------" . PHP_EOL;
} }
``` ```
Iterator zip entries. or
```php ```php
$iterator = new \ArrayIterator($zipFile); $iterator = new \ArrayIterator($zipFile);
while ($iterator->valid()) while ($iterator->valid())
@ -105,58 +154,54 @@ while ($iterator->valid())
$iterator->next(); $iterator->next();
} }
``` ```
Checks whether a entry exists.
```php
$boolValue = $zipFile->hasEntry($entryName);
```
Check whether the directory entry.
```php
$boolValue = $zipFile->isDirectory($entryName);
```
Set password to all encrypted entries.
```php
$zipFile->setPassword($password);
```
Set password to concrete zip entry.
```php
$zipFile->setEntryPassword($entryName, $password);
```
Get comment archive. Get comment archive.
```php ```php
$commentArchive = $zipFile->getComment(); $commentArchive = $zipFile->getArchiveComment();
``` ```
Get comment zip entry. Get comment zip entry.
```php ```php
$commentEntry = $zipFile->getEntryComment($entryName); $commentEntry = $zipFile->getEntryComment($entryName);
``` ```
Set password for read encrypted entries.
```php
$zipFile->withReadPassword($password);
```
Get entry info. Get entry info.
```php ```php
$zipInfo = $zipFile->getEntryInfo('file.txt'); $zipInfo = $zipFile->getEntryInfo('file.txt');
echo $zipInfo . PHP_EOL; echo $zipInfo . PHP_EOL;
// Output:
// ZipInfo {Path="file.txt", Size=9.77KB, Compressed size=2.04KB, Modified time=2016-09-24T19:25:10+03:00, Crc=0x4b5ab5c7, Method="Deflate", Attributes="-rw-r--r--", Platform="UNIX", Version=20} // ZipInfo {Path="file.txt", Size=9.77KB, Compressed size=2.04KB, Modified time=2016-09-24T19:25:10+03:00, Crc=0x4b5ab5c7, Method="Deflate", Attributes="-rw-r--r--", Platform="UNIX", Version=20}
print_r($zipInfo); print_r($zipInfo);
//PhpZip\Model\ZipInfo Object
//( // Output:
// [path:PhpZip\Model\ZipInfo:private] => file.txt // PhpZip\Model\ZipInfo Object
// [folder:PhpZip\Model\ZipInfo:private] => // (
// [size:PhpZip\Model\ZipInfo:private] => 10000 // [path:PhpZip\Model\ZipInfo:private] => file.txt
// [compressedSize:PhpZip\Model\ZipInfo:private] => 2086 // [folder:PhpZip\Model\ZipInfo:private] =>
// [mtime:PhpZip\Model\ZipInfo:private] => 1474734310 // [size:PhpZip\Model\ZipInfo:private] => 10000
// [ctime:PhpZip\Model\ZipInfo:private] => // [compressedSize:PhpZip\Model\ZipInfo:private] => 2086
// [atime:PhpZip\Model\ZipInfo:private] => // [mtime:PhpZip\Model\ZipInfo:private] => 1474734310
// [encrypted:PhpZip\Model\ZipInfo:private] => // [ctime:PhpZip\Model\ZipInfo:private] =>
// [comment:PhpZip\Model\ZipInfo:private] => // [atime:PhpZip\Model\ZipInfo:private] =>
// [crc:PhpZip\Model\ZipInfo:private] => 1264235975 // [encrypted:PhpZip\Model\ZipInfo:private] =>
// [method:PhpZip\Model\ZipInfo:private] => Deflate // [comment:PhpZip\Model\ZipInfo:private] =>
// [platform:PhpZip\Model\ZipInfo:private] => UNIX // [crc:PhpZip\Model\ZipInfo:private] => 1264235975
// [version:PhpZip\Model\ZipInfo:private] => 20 // [method:PhpZip\Model\ZipInfo:private] => Deflate
// [attributes:PhpZip\Model\ZipInfo:private] => -rw-r--r-- // [platform:PhpZip\Model\ZipInfo:private] => UNIX
//) // [version:PhpZip\Model\ZipInfo:private] => 20
// [attributes:PhpZip\Model\ZipInfo:private] => -rw-r--r--
// )
``` ```
Get info for all entries. Get info for all entries.
```php ```php
$zipAllInfo = $zipFile->getAllInfo(); $zipAllInfo = $zipFile->getAllInfo();
print_r($zipAllInfo); print_r($zipAllInfo);
//Array //Array
//( //(
// [file.txt] => PhpZip\Model\ZipInfo Object // [file.txt] => PhpZip\Model\ZipInfo Object
@ -171,90 +216,77 @@ print_r($zipAllInfo);
// //
// ... // ...
//) //)
```
Extract all files to directory.
```php
$zipFile->extractTo($directory);
```
Extract some files to directory.
```php
$extractOnlyFiles = ["filename1", "filename2", "dir/dir/dir/"];
$zipFile->extractTo($directory, $extractOnlyFiles);
```
Get entry content.
```php
$data = $zipFile->getEntryContent($entryName);
```
Edit zip archive
```php
$zipOutputFile = $zipFile->edit();
```
Close zip archive.
```php
$zipFile->close();
```
#### Class `\PhpZip\ZipOutputFile` (create, update, extract)
Create zip archive.
```php
$zipOutputFile = new \PhpZip\ZipOutputFile();
// or
$zipOutputFile = \PhpZip\ZipOutputFile::create();
```
Open zip file from update.
```php
$filename = "file.zip";
$zipOutputFile = \PhpZip\ZipOutputFile::openFromFile($filename);
```
or
```php
// initial ZipFile
$zipFile = \PhpZip\ZipFile::openFromFile($filename);
// Create output stream from update zip file ###### <a name="Documentation-Add-Zip-Entries"></a> Add Zip Entries
$zipOutputFile = new \PhpZip\ZipOutputFile($zipFile);
// or
$zipOutputFile = \PhpZip\ZipOutputFile::openFromZipFile($zipFile);
// or
$zipOutputFile = $zipFile->edit();
``` ```
Add entry from file. Adding a file to the zip-archive.
```php ```php
$zipOutputFile->addFromFile($filename); // $entryName == basename($filename); // entry name is file basename.
$zipOutputFile->addFromFile($filename, $entryName); $zipFile->addFile($filename);
$zipOutputFile->addFromFile($filename, $entryName, ZipEntry::METHOD_DEFLATED); // or
$zipOutputFile->addFromFile($filename, $entryName, ZipEntry::METHOD_STORED); // no compress $zipFile->addFile($filename, null);
$zipOutputFile->addFromFile($filename, null, ZipEntry::METHOD_BZIP2); // $entryName == basename($filename);
// with entry name
$zipFile->addFile($filename, $entryName);
// or
$zipFile[$entryName] = new \SplFileInfo($filename);
// with compression method
$zipOFile->addFile($filename, $entryName, ZipFile::METHOD_DEFLATED); // Deflate compression
$zipFile->addFile($filename, $entryName, ZipFile::METHOD_STORED); // No compression
$zipFile->addFile($filename, null, ZipFile::METHOD_BZIP2); // BZIP2 compression
``` ```
Add entry from string data. Add entry from string data.
```php ```php
$zipOutputFile->addFromString($entryName, $data); $zipFile[$entryName] = $data;
$zipOutputFile->addFromString($entryName, $data, ZipEntry::METHOD_DEFLATED); // or
$zipOutputFile->addFromString($entryName, $data, ZipEntry::METHOD_STORED); // no compress $zipFile->addFromString($entryName, $data);
// with compression method
$zipFile->addFromString($entryName, $data, ZipFile::METHOD_DEFLATED); // Deflate compression
$zipFile->addFromString($entryName, $data, ZipFile::METHOD_STORED); // No compression
$zipFile->addFromString($entryName, $data, ZipFile::METHOD_BZIP2); // BZIP2 compression
``` ```
Add entry from stream. Add entry from stream.
```php ```php
$zipOutputFile->addFromStream($stream, $entryName); // $stream = fopen(...);
$zipOutputFile->addFromStream($stream, $entryName, ZipEntry::METHOD_DEFLATED);
$zipOutputFile->addFromStream($stream, $entryName, ZipEntry::METHOD_STORED); // no compress $zipFile->addFromStream($stream, $entryName);
// with compression method
$zipFile->addFromStream($stream, $entryName, ZipFile::METHOD_DEFLATED); Deflate compression
$zipFile->addFromStream($stream, $entryName, ZipFile::METHOD_STORED); // No compression
$zipFile->addFromStream($stream, $entryName, ZipFile::METHOD_BZIP2); // BZIP2 compression
``` ```
Add empty dir Add empty dir
```php ```php
$zipOutputFile->addEmptyDir($dirName); $zipFile->addEmptyDir($dirName);
```
Add a directory **recursively** to the archive.
```php
$zipOutputFile->addDir($dirName);
// or // or
$zipOutputFile->addDir($dirName, true); $zipFile[$dirName] = null;
```
Add all entries form string contents.
```php
$mapData = [
'file.txt' => 'file contents',
'path/to/file.txt' => 'another file contents',
'empty dir/' => null,
];
$zipFile->addAll($mapData);
``` ```
Add a directory **not recursively** to the archive. Add a directory **not recursively** to the archive.
```php ```php
$zipOutputFile->addDir($dirName, false); $zipFile->addDir($dirName);
```
Add a directory to the archive by path `$moveToPath` // with entry path
```php $localPath = "to/path/";
$moveToPath = 'dir/subdir/'; $zipFile->addDir($dirName, $localPath);
$zipOutputFile->addDir($dirName, $boolResursive, $moveToPath);
// with compression method for all files
$zipFile->addDir($dirName, $localPath, ZipFile::METHOD_DEFLATED); Deflate compression
$zipFile->addDir($dirName, $localPath, ZipFile::METHOD_STORED); // No compression
$zipFile->addDir($dirName, $localPath, ZipFile::METHOD_BZIP2); // BZIP2 compression
``` ```
Add a directory to the archive with ignoring files. Add a directory to the archive with ignoring files.
```php ```php
@ -263,7 +295,7 @@ $zipOutputFile->addDir($dirName, $boolResursive, $moveToPath, $ignoreFiles);
``` ```
Add a directory and set compression method. Add a directory and set compression method.
```php ```php
$compressionMethod = ZipEntry::METHOD_DEFLATED; $compressionMethod = ZipFile::METHOD_DEFLATED;
$zipOutputFile->addDir($dirName, $boolRecursive, $moveToPath, $ignoreFiles, $compressionMethod); $zipOutputFile->addDir($dirName, $boolRecursive, $moveToPath, $ignoreFiles, $compressionMethod);
``` ```
Add a files **recursively** from [glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)) to the archive. Add a files **recursively** from [glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)) to the archive.
@ -283,7 +315,7 @@ $zipOutputFile->addFilesFromGlob($inputDir, $globPattern, $recursive = true, $mo
``` ```
Add a files from [glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)) to the archive and set compression method. Add a files from [glob pattern](https://en.wikipedia.org/wiki/Glob_(programming)) to the archive and set compression method.
```php ```php
$compressionMethod = ZipEntry::METHOD_DEFLATED; $compressionMethod = ZipFile::METHOD_DEFLATED;
$zipOutputFile->addFilesFromGlob($inputDir, $globPattern, $recursive, $moveToPath, $compressionMethod); $zipOutputFile->addFilesFromGlob($inputDir, $globPattern, $recursive, $moveToPath, $compressionMethod);
``` ```
Add a files **recursively** from [RegEx (Regular Expression) pattern](https://en.wikipedia.org/wiki/Regular_expression) to the archive. Add a files **recursively** from [RegEx (Regular Expression) pattern](https://en.wikipedia.org/wiki/Regular_expression) to the archive.
@ -303,7 +335,7 @@ $zipOutputFile->addFilesFromRegex($inputDir, $regexPattern, $recursive = true, $
``` ```
Add a files from [RegEx (Regular Expression) pattern](https://en.wikipedia.org/wiki/Regular_expression) to the archive and set compression method. Add a files from [RegEx (Regular Expression) pattern](https://en.wikipedia.org/wiki/Regular_expression) to the archive and set compression method.
```php ```php
$compressionMethod = ZipEntry::METHOD_DEFLATED; $compressionMethod = ZipFile::METHOD_DEFLATED;
$zipOutputFile->addFilesFromRegex($inputDir, $regexPattern, $recursive, $moveToPath, $compressionMethod); $zipOutputFile->addFilesFromRegex($inputDir, $regexPattern, $recursive, $moveToPath, $compressionMethod);
``` ```
Rename entry name. Rename entry name.
@ -368,13 +400,13 @@ $zipOutputFile->setEntryComment($entryName, $entryComment);
``` ```
Set compression method for zip entry. Set compression method for zip entry.
```php ```php
$compressionMethod = ZipEntry::METHOD_DEFLATED; $compressionMethod = ZipFile::METHOD_DEFLATED;
$zipOutputMethod->setCompressionMethod($entryName, $compressionMethod); $zipOutputMethod->setCompressionMethod($entryName, $compressionMethod);
// Support compression methods: // Support compression methods:
// ZipEntry::METHOD_STORED - no compression // ZipFile::METHOD_STORED - no compression
// ZipEntry::METHOD_DEFLATED - deflate compression // ZipFile::METHOD_DEFLATED - deflate compression
// ZipEntry::METHOD_BZIP2 - bzip2 compression (need bz2 extension) // ZipFile::METHOD_BZIP2 - bzip2 compression (need bz2 extension)
``` ```
Set a password for all previously added entries. Set a password for all previously added entries.
```php ```php
@ -382,12 +414,12 @@ $zipOutputFile->setPassword($password);
``` ```
Set a password and encryption method for all previously added entries. Set a password and encryption method for all previously added entries.
```php ```php
$encryptionMethod = ZipEntry::ENCRYPTION_METHOD_WINZIP_AES; // default value $encryptionMethod = ZipFile::ENCRYPTION_METHOD_WINZIP_AES; // default value
$zipOutputFile->setPassword($password, $encryptionMethod); $zipOutputFile->setPassword($password, $encryptionMethod);
// Support encryption methods: // Support encryption methods:
// ZipEntry::ENCRYPTION_METHOD_TRADITIONAL - Traditional PKWARE Encryption // ZipFile::ENCRYPTION_METHOD_TRADITIONAL - Traditional PKWARE Encryption
// ZipEntry::ENCRYPTION_METHOD_WINZIP_AES - WinZip AES Encryption // ZipFile::ENCRYPTION_METHOD_WINZIP_AES - WinZip AES Encryption
``` ```
Set a password for a concrete entry. Set a password for a concrete entry.
```php ```php
@ -398,8 +430,8 @@ Set a password and encryption method for a concrete entry.
$zipOutputFile->setEntryPassword($entryName, $password, $encryptionMethod); $zipOutputFile->setEntryPassword($entryName, $password, $encryptionMethod);
// Support encryption methods: // Support encryption methods:
// ZipEntry::ENCRYPTION_METHOD_TRADITIONAL - Traditional PKWARE Encryption // ZipFile::ENCRYPTION_METHOD_TRADITIONAL - Traditional PKWARE Encryption
// ZipEntry::ENCRYPTION_METHOD_WINZIP_AES - WinZip AES Encryption (default value) // ZipFile::ENCRYPTION_METHOD_WINZIP_AES - WinZip AES Encryption (default value)
``` ```
Remove password from all entries. Remove password from all entries.
```php ```php