mirror of
https://github.com/Ne-Lexa/php-zip.git
synced 2025-03-13 19:19:42 +01:00
README update
This commit is contained in:
Ne-Lexa
parent
1e4b14177a
commit
0dbdc0faeb
324
README.md
324
README.md
@ -4,10 +4,22 @@
|
||||
|
||||
[](https://packagist.org/packages/nelexa/zip)
|
||||
[](https://packagist.org/packages/nelexa/zip)
|
||||
[](https://php.net/)
|
||||
[](https://codeclimate.com/github/Ne-Lexa/php-zip/coverage)
|
||||
[](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.
|
||||
- Create zip files.
|
||||
- Update zip files.
|
||||
@ -20,42 +32,38 @@ Features:
|
||||
- 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).
|
||||
|
||||
Requirements
|
||||
------------
|
||||
### <a name="Requirements"></a> Requirements
|
||||
- `PHP` >= 5.5 (64 bit)
|
||||
- Optional php-extension `bzip2` for BZIP2 compression.
|
||||
- Optional php-extension `openssl` or `mcrypt` for `WinZip Aes Encryption` support.
|
||||
|
||||
Installation
|
||||
------------
|
||||
### <a name="Installation"></a> Installation
|
||||
`composer require nelexa/zip:^3.0`
|
||||
|
||||
Samples
|
||||
-------
|
||||
### <a name="Examples"></a> Examples
|
||||
```php
|
||||
// create archive
|
||||
// create new archive
|
||||
$zipFile = new \PhpZip\ZipFile();
|
||||
$zipFile->addFromString("zip/entry/filename", "Is file content")
|
||||
->addFile("/path/to/file", "data/tofile")
|
||||
->addDir(__DIR__, "to/path/")
|
||||
->saveAsFile($outputFilename)
|
||||
->close();
|
||||
$zipFile
|
||||
->addFromString("zip/entry/filename", "Is file content")
|
||||
->addFile("/path/to/file", "data/tofile")
|
||||
->addDir(__DIR__, "to/path/")
|
||||
->saveAsFile($outputFilename)
|
||||
->close();
|
||||
|
||||
// open archive, extract, add files, set password and output to browser.
|
||||
$zipFile->openFile($outputFilename)
|
||||
->extractTo($outputDirExtract)
|
||||
->deleteFromRegex('~^\.~') // delete all hidden (Unix) files
|
||||
->addFromString('dir/file.txt', 'Test file')
|
||||
->withNewPassword('password')
|
||||
->outputAsAttachment('library.jar');
|
||||
$zipFile
|
||||
->openFile($outputFilename)
|
||||
->extractTo($outputDirExtract)
|
||||
->deleteFromRegex('~^\.~') // delete all hidden (Unix) files
|
||||
->addFromString('dir/file.txt', 'Test file')
|
||||
->withNewPassword('password')
|
||||
->outputAsAttachment('library.jar');
|
||||
```
|
||||
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.
|
||||
```php
|
||||
$zipFile = new \PhpZip\ZipFile();
|
||||
@ -63,26 +71,67 @@ $zipFile->openFile($filename);
|
||||
```
|
||||
Open zip archive from data string.
|
||||
```php
|
||||
$data = file_get_contents($urlOrFile);
|
||||
$zipFile = new \PhpZip\ZipFile();
|
||||
$zipFile->openFromString($filename);
|
||||
$zipFile->openFromString($stringContents);
|
||||
```
|
||||
Open zip archive from stream resource.
|
||||
```php
|
||||
$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.
|
||||
```php
|
||||
$count = $zipFile->count();
|
||||
// or
|
||||
$count = count($zipFile);
|
||||
// or
|
||||
$count = $zipFile->count();
|
||||
```
|
||||
Get list files.
|
||||
```php
|
||||
$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
|
||||
foreach($zipFile as $entryName => $dataContent){
|
||||
echo "Entry: $entryName" . PHP_EOL;
|
||||
@ -90,7 +139,7 @@ foreach($zipFile as $entryName => $dataContent){
|
||||
echo "-----------------------------" . PHP_EOL;
|
||||
}
|
||||
```
|
||||
Iterator zip entries.
|
||||
or
|
||||
```php
|
||||
$iterator = new \ArrayIterator($zipFile);
|
||||
while ($iterator->valid())
|
||||
@ -105,58 +154,54 @@ while ($iterator->valid())
|
||||
$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.
|
||||
```php
|
||||
$commentArchive = $zipFile->getComment();
|
||||
$commentArchive = $zipFile->getArchiveComment();
|
||||
```
|
||||
Get comment zip entry.
|
||||
```php
|
||||
$commentEntry = $zipFile->getEntryComment($entryName);
|
||||
```
|
||||
Set password for read encrypted entries.
|
||||
```php
|
||||
$zipFile->withReadPassword($password);
|
||||
```
|
||||
Get entry info.
|
||||
```php
|
||||
$zipInfo = $zipFile->getEntryInfo('file.txt');
|
||||
|
||||
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}
|
||||
|
||||
print_r($zipInfo);
|
||||
//PhpZip\Model\ZipInfo Object
|
||||
//(
|
||||
// [path:PhpZip\Model\ZipInfo:private] => file.txt
|
||||
// [folder:PhpZip\Model\ZipInfo:private] =>
|
||||
// [size:PhpZip\Model\ZipInfo:private] => 10000
|
||||
// [compressedSize:PhpZip\Model\ZipInfo:private] => 2086
|
||||
// [mtime:PhpZip\Model\ZipInfo:private] => 1474734310
|
||||
// [ctime:PhpZip\Model\ZipInfo:private] =>
|
||||
// [atime:PhpZip\Model\ZipInfo:private] =>
|
||||
// [encrypted:PhpZip\Model\ZipInfo:private] =>
|
||||
// [comment:PhpZip\Model\ZipInfo:private] =>
|
||||
// [crc:PhpZip\Model\ZipInfo:private] => 1264235975
|
||||
// [method:PhpZip\Model\ZipInfo:private] => Deflate
|
||||
// [platform:PhpZip\Model\ZipInfo:private] => UNIX
|
||||
// [version:PhpZip\Model\ZipInfo:private] => 20
|
||||
// [attributes:PhpZip\Model\ZipInfo:private] => -rw-r--r--
|
||||
//)
|
||||
|
||||
// Output:
|
||||
// PhpZip\Model\ZipInfo Object
|
||||
// (
|
||||
// [path:PhpZip\Model\ZipInfo:private] => file.txt
|
||||
// [folder:PhpZip\Model\ZipInfo:private] =>
|
||||
// [size:PhpZip\Model\ZipInfo:private] => 10000
|
||||
// [compressedSize:PhpZip\Model\ZipInfo:private] => 2086
|
||||
// [mtime:PhpZip\Model\ZipInfo:private] => 1474734310
|
||||
// [ctime:PhpZip\Model\ZipInfo:private] =>
|
||||
// [atime:PhpZip\Model\ZipInfo:private] =>
|
||||
// [encrypted:PhpZip\Model\ZipInfo:private] =>
|
||||
// [comment:PhpZip\Model\ZipInfo:private] =>
|
||||
// [crc:PhpZip\Model\ZipInfo:private] => 1264235975
|
||||
// [method:PhpZip\Model\ZipInfo:private] => Deflate
|
||||
// [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.
|
||||
```php
|
||||
$zipAllInfo = $zipFile->getAllInfo();
|
||||
|
||||
print_r($zipAllInfo);
|
||||
|
||||
//Array
|
||||
//(
|
||||
// [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
|
||||
$zipOutputFile = new \PhpZip\ZipOutputFile($zipFile);
|
||||
// or
|
||||
$zipOutputFile = \PhpZip\ZipOutputFile::openFromZipFile($zipFile);
|
||||
// or
|
||||
$zipOutputFile = $zipFile->edit();
|
||||
###### <a name="Documentation-Add-Zip-Entries"></a> Add Zip Entries
|
||||
```
|
||||
Add entry from file.
|
||||
Adding a file to the zip-archive.
|
||||
```php
|
||||
$zipOutputFile->addFromFile($filename); // $entryName == basename($filename);
|
||||
$zipOutputFile->addFromFile($filename, $entryName);
|
||||
$zipOutputFile->addFromFile($filename, $entryName, ZipEntry::METHOD_DEFLATED);
|
||||
$zipOutputFile->addFromFile($filename, $entryName, ZipEntry::METHOD_STORED); // no compress
|
||||
$zipOutputFile->addFromFile($filename, null, ZipEntry::METHOD_BZIP2); // $entryName == basename($filename);
|
||||
// entry name is file basename.
|
||||
$zipFile->addFile($filename);
|
||||
// or
|
||||
$zipFile->addFile($filename, null);
|
||||
|
||||
// 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.
|
||||
```php
|
||||
$zipOutputFile->addFromString($entryName, $data);
|
||||
$zipOutputFile->addFromString($entryName, $data, ZipEntry::METHOD_DEFLATED);
|
||||
$zipOutputFile->addFromString($entryName, $data, ZipEntry::METHOD_STORED); // no compress
|
||||
$zipFile[$entryName] = $data;
|
||||
// or
|
||||
$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.
|
||||
```php
|
||||
$zipOutputFile->addFromStream($stream, $entryName);
|
||||
$zipOutputFile->addFromStream($stream, $entryName, ZipEntry::METHOD_DEFLATED);
|
||||
$zipOutputFile->addFromStream($stream, $entryName, ZipEntry::METHOD_STORED); // no compress
|
||||
// $stream = fopen(...);
|
||||
|
||||
$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
|
||||
```php
|
||||
$zipOutputFile->addEmptyDir($dirName);
|
||||
```
|
||||
Add a directory **recursively** to the archive.
|
||||
```php
|
||||
$zipOutputFile->addDir($dirName);
|
||||
$zipFile->addEmptyDir($dirName);
|
||||
// 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.
|
||||
```php
|
||||
$zipOutputFile->addDir($dirName, false);
|
||||
```
|
||||
Add a directory to the archive by path `$moveToPath`
|
||||
```php
|
||||
$moveToPath = 'dir/subdir/';
|
||||
$zipOutputFile->addDir($dirName, $boolResursive, $moveToPath);
|
||||
$zipFile->addDir($dirName);
|
||||
|
||||
// with entry path
|
||||
$localPath = "to/path/";
|
||||
$zipFile->addDir($dirName, $localPath);
|
||||
|
||||
// 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.
|
||||
```php
|
||||
@ -263,7 +295,7 @@ $zipOutputFile->addDir($dirName, $boolResursive, $moveToPath, $ignoreFiles);
|
||||
```
|
||||
Add a directory and set compression method.
|
||||
```php
|
||||
$compressionMethod = ZipEntry::METHOD_DEFLATED;
|
||||
$compressionMethod = ZipFile::METHOD_DEFLATED;
|
||||
$zipOutputFile->addDir($dirName, $boolRecursive, $moveToPath, $ignoreFiles, $compressionMethod);
|
||||
```
|
||||
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.
|
||||
```php
|
||||
$compressionMethod = ZipEntry::METHOD_DEFLATED;
|
||||
$compressionMethod = ZipFile::METHOD_DEFLATED;
|
||||
$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.
|
||||
@ -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.
|
||||
```php
|
||||
$compressionMethod = ZipEntry::METHOD_DEFLATED;
|
||||
$compressionMethod = ZipFile::METHOD_DEFLATED;
|
||||
$zipOutputFile->addFilesFromRegex($inputDir, $regexPattern, $recursive, $moveToPath, $compressionMethod);
|
||||
```
|
||||
Rename entry name.
|
||||
@ -368,13 +400,13 @@ $zipOutputFile->setEntryComment($entryName, $entryComment);
|
||||
```
|
||||
Set compression method for zip entry.
|
||||
```php
|
||||
$compressionMethod = ZipEntry::METHOD_DEFLATED;
|
||||
$compressionMethod = ZipFile::METHOD_DEFLATED;
|
||||
$zipOutputMethod->setCompressionMethod($entryName, $compressionMethod);
|
||||
|
||||
// Support compression methods:
|
||||
// ZipEntry::METHOD_STORED - no compression
|
||||
// ZipEntry::METHOD_DEFLATED - deflate compression
|
||||
// ZipEntry::METHOD_BZIP2 - bzip2 compression (need bz2 extension)
|
||||
// ZipFile::METHOD_STORED - no compression
|
||||
// ZipFile::METHOD_DEFLATED - deflate compression
|
||||
// ZipFile::METHOD_BZIP2 - bzip2 compression (need bz2 extension)
|
||||
```
|
||||
Set a password for all previously added entries.
|
||||
```php
|
||||
@ -382,12 +414,12 @@ $zipOutputFile->setPassword($password);
|
||||
```
|
||||
Set a password and encryption method for all previously added entries.
|
||||
```php
|
||||
$encryptionMethod = ZipEntry::ENCRYPTION_METHOD_WINZIP_AES; // default value
|
||||
$encryptionMethod = ZipFile::ENCRYPTION_METHOD_WINZIP_AES; // default value
|
||||
$zipOutputFile->setPassword($password, $encryptionMethod);
|
||||
|
||||
// Support encryption methods:
|
||||
// ZipEntry::ENCRYPTION_METHOD_TRADITIONAL - Traditional PKWARE Encryption
|
||||
// ZipEntry::ENCRYPTION_METHOD_WINZIP_AES - WinZip AES Encryption
|
||||
// ZipFile::ENCRYPTION_METHOD_TRADITIONAL - Traditional PKWARE Encryption
|
||||
// ZipFile::ENCRYPTION_METHOD_WINZIP_AES - WinZip AES Encryption
|
||||
```
|
||||
Set a password for a concrete entry.
|
||||
```php
|
||||
@ -398,8 +430,8 @@ Set a password and encryption method for a concrete entry.
|
||||
$zipOutputFile->setEntryPassword($entryName, $password, $encryptionMethod);
|
||||
|
||||
// Support encryption methods:
|
||||
// ZipEntry::ENCRYPTION_METHOD_TRADITIONAL - Traditional PKWARE Encryption
|
||||
// ZipEntry::ENCRYPTION_METHOD_WINZIP_AES - WinZip AES Encryption (default value)
|
||||
// ZipFile::ENCRYPTION_METHOD_TRADITIONAL - Traditional PKWARE Encryption
|
||||
// ZipFile::ENCRYPTION_METHOD_WINZIP_AES - WinZip AES Encryption (default value)
|
||||
```
|
||||
Remove password from all entries.
|
||||
```php
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user