summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPaul Duncan <pabs@pablotron.org>2018-09-03 09:39:02 -0400
committerPaul Duncan <pabs@pablotron.org>2018-09-03 09:54:54 -0400
commit1fbf6c466dc01d63ba119e4614ef9190ee9d87ff (patch)
tree09c735cae623eb60995a9fcd2c85c61497a95b1d
parenteca42d118e439dc0f3796650e8a68992d513f8ee (diff)
downloadzipstream-php-1fbf6c466dc01d63ba119e4614ef9190ee9d87ff.tar.bz2
zipstream-php-1fbf6c466dc01d63ba119e4614ef9190ee9d87ff.zip
add README.mkd, examples/examples.json, and minor comment cleanups
-rw-r--r--README.mkd125
-rw-r--r--examples/examples.json43
-rw-r--r--src/ZipStream.php2
-rw-r--r--tests/LargeFileTest.php5
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) {