diff options
| -rw-r--r-- | README.mkd | 125 | ||||
| -rw-r--r-- | examples/examples.json | 43 | ||||
| -rw-r--r-- | src/ZipStream.php | 2 | ||||
| -rw-r--r-- | tests/LargeFileTest.php | 5 |
4 files changed, 173 insertions, 2 deletions
diff --git a/README.mkd b/README.mkd new file mode 100644 index 0000000..19ee691 --- /dev/null +++ b/README.mkd @@ -0,0 +1,125 @@ +ZipStream-PHP 0.3.0 +=================== + +Overview +-------- +ZipStream-PHP is a library that allows you to dynamically generate +streamed zip archives. + +Here's an example: + + # import zipstream class + use Pablotron\ZipStream\ZipStream; + + # create the output stream + $zip = new ZipStream('example.zip'); + + # add a file named "hello.txt" to output archive, containing the + # string "hello world!" + $zip->add_file('hello.txt', 'hello world!'); + + # add a local file named "some-image.png" to the output archive as + # "picture.png" + $zip->add_file_from_path('picture.png', 'some-image.png'); + + # finalize the output stream + $zip->close(); + +Features: + +* Generate streamed archives without saving them to disk. +* Files can be read from files, strings, streaming resources, + or generated dynamically. +* Zip64 support: files and archives up to <code>2<sup>64</sup></code> + bytes in size +* Stream output as an HTTP response, to a file on disk, to a resource + stream, or to a custom target. +* [MIT][mit]-licensed: Use freely, even in commercial projects -- + without restrictions. +* Self-contained: Single source file with no required external + dependencies, so you can easily embed `ZipStream.php` directly into + your source tree if necessary. + +Dependencies +------------ + +* PHP: 7.0 or newer (required). +* [Composer][composer]: Used for installation (optional, see below). +* [phpDocumentor][phpdoc]: Used to generate the API documentation (optional). +* [PHPUnit][phpunit]: Used to run the test suite (optional). + +*Note:* Consider an older version of ZipStream if you need PHP 5.x +support. + +Installation +------------ +### Using [Composer][composer] + + # in your project root + composer require pablotron/zipstream + +Or add it to your top-level `composer.json`, like so: + + "require": { + "pablotron/zipstream": "~0.3" + }, + +### Manual Installation +The source file for ZipStream is entirely self-contained, which means +you can embed it directly in your project without using +[Composer][composer] by doing the following: + + # copy file to your project + cp src/ZipStream.php path/to/your/project/ + + # then, somewhere in your project... + require_once 'path/to/ZipStream.php'; + +Documentation +------------- +The API documentation is available online at the following URL: + +https://pablotron.github.io/zipstream-php/ + +You can generate the API documentation using [Composer][composer], like +so: + + # generate api documentation in "docs/" directory + composer docs + +Brief usage examples are available in the `examples/` directory. + +Tests +----- +You can run the test suite via [Composer][composer] like so: + + # run the test suite + composer test + +License +------- +Copyright 2007-2018 Paul Duncan <pabs@pablotron.org> + +Permission is hereby granted, free of charge, to any person obtaining a +copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +[composer]: https://getcomposer.org/ +[mit]: https://opensource.org/licenses/MIT +[phpunit]: https://phpunit.de/ +[phpdoc]: https://phpdoc.org/ diff --git a/examples/examples.json b/examples/examples.json new file mode 100644 index 0000000..f754a07 --- /dev/null +++ b/examples/examples.json @@ -0,0 +1,43 @@ +{ + "examples": [{ + "file": "01-simple.php", + "text": "Basic usage example." + }, { + "file": "02-add_file_from_path.php", + "text": "Add a file from a path." + }, { + "file": "03-add_stream.php", + "text": "Add file from a resource stream." + }, { + "file": "04-add.php", + "text": "Add a dynamically-generated file." + }, { + "file": "05-send.php", + "text": "Use `ZipStream::send`." + }, { + "file": "06-file_writer.php", + "text": "Write output to a file." + }, { + "file": "07-stream_writer.php", + "text": "Write output to a resource stream." + }, { + "file": "08-datetime.php", + "text": "Use a `DateTime` instance directly." + }, { + "file": "09-version.php", + "text": "Get the version of ZipStream." + }, { + "file": "10-archive_comment.php", + "text": "Add an archive comment." + }, { + "file": "11-add_file_comment.php", + "text": "Add a file comment." + }, { + "file": "12-add_file_methods.php", + "text": "Add a file with a specific compression method." + }, { + "file": "13-add_file_times.php", + "text": "Add a file with a specific modification time." + }] +} + diff --git a/src/ZipStream.php b/src/ZipStream.php index 437ff1d..8648b9f 100644 --- a/src/ZipStream.php +++ b/src/ZipStream.php @@ -14,6 +14,8 @@ namespace Pablotron\ZipStream; /** * Current version of ZipStream. + * + * @api */ const VERSION = '0.3.0'; diff --git a/tests/LargeFileTest.php b/tests/LargeFileTest.php index c271b47..b1106ec 100644 --- a/tests/LargeFileTest.php +++ b/tests/LargeFileTest.php @@ -8,11 +8,12 @@ use \Pablotron\ZipStream\ZipStream; final class LargeFileTest extends BaseTestCase { public function testCreateLargeFile() : void { - # build 4M string + # size and number of chunks $chunk_size = (1 << 22); $num_chunks = 1025; - # calculate expected size + # calculate expected file size (4299161600, enough to overflow a + # 32-bit integer and trigger zip64 mode) $expected_size = $chunk_size * $num_chunks; $this->with_temp_zip(function(ZipStream &$zip) use ($chunk_size, $num_chunks) { |