Migrate Wiki into Guides (#228)

Author: maennchen

.github/CONTRIBUTING.md

@@ -135,3 +135,5 @@ To generate the documentation for the library, run:
 ```bash
 $ composer run docs:generate
 ```
+
+The guide documentation pages can be found in the `/guides/` directory.

README.md

@@ -26,7 +26,7 @@ Simply add a dependency on maennchen/zipstream-php to your project's composer.js
 composer require maennchen/zipstream-php
 ```
 
-## Usage and options
+## Usage
 
 For detailed instructions, please check the
 [Documentation](https://maennchen.dev/ZipStream-PHP/).
@@ -50,31 +50,10 @@ $zip->addFile('hello.txt', 'This is the contents of hello.txt');
 // add a file named 'some_image.jpg' from a local file 'path/to/image.jpg'
 $zip->addFileFromPath('some_image.jpg', 'path/to/image.jpg');
 
-// add a file named 'goodbye.txt' from an open stream resource
-$fp = tmpfile();
-fwrite($fp, 'The quick brown fox jumped over the lazy dog.');
-rewind($fp);
-$zip->addFileFromStream('goodbye.txt', $fp);
-fclose($fp);
-
 // finish the zip stream
 $zip->finish();
 ```
 
-You can also add comments, modify file timestamps, and customize (or
-disable) the HTTP headers. It is also possible to specify the storage method when adding files,
-the current default storage method is 'deflate' i.e files are stored with Compression mode 0x08.
-
-See the [Wiki](https://github.com/maennchen/ZipStream-PHP/wiki) for details.
-
-## Known issues
-
-The native Mac OS archive extraction tool prior to macOS 10.15 might not open archives in some conditions. A workaround is to disable the Zip64 feature with the option `$opt->setEnableZip64(false)`. This limits the archive to 4 Gb and 64k files but will allow users on macOS 10.14 and below to open them without issue. See #116.
-
-The linux `unzip` utility might not handle properly unicode characters. It is recommended to extract with another tool like [7-zip](https://www.7-zip.org/). See [#146](https://github.com/maennchen/ZipStream-PHP/issues/146).
-
-It is the responsability of the client code to make sure that files are not saved with the same path, as it is not possible for the library to figure it out while streaming a zip. See [#154](https://github.com/maennchen/ZipStream-PHP/issues/154).
-
 ## Upgrade to version 2.0.0
 
 - Only the self opened streams will be closed (#139)

composer.json

@@ -58,6 +58,7 @@
       "/.gitattributes",
       "/.github",
       "/.gitignore",
+      "/guides",
       "/.phive",
       "/.php-cs-fixer.cache",
       "/.php-cs-fixer.dist.php",

guides/ContentLength.rst

@@ -0,0 +1,79 @@
+Adding Content-Length header
+=============
+
+Adding a ``Content-Length`` header for ``ZipStream`` is not trivial since the
+size is not known beforehand.
+
+The following workaround adds an approximated header:
+
+.. code-block:: php
+
+    class Zip
+    {
+        /** @var string */
+        private $name;
+
+        private $files = [];
+
+        public function __construct($name)
+        {
+            $this->name = $name;
+        }
+
+        public function addFile($name, $data)
+        {
+            $this->files[] = ['type' => 'addFile', 'name' => $name, 'data' => $data];
+        }
+
+        public function addFileFromPath($name, $path)
+        {
+            $this->files[] = ['type' => 'addFileFromPath', 'name' => $name, 'path' => $path];
+        }
+
+        public function getEstimate()
+        {
+            $estimate = 22;
+            foreach ($this->files as $file) {
+            $estimate += 76 + 2 * strlen($file['name']);
+            if ($file['type'] === 'addFile') {
+                $estimate += strlen($file['data']);
+            }
+            if ($file['type'] === 'addFileFromPath') {
+                $estimate += filesize($file['path']);
+            }
+            }
+            return $estimate;
+        }
+
+        public function finish()
+        {
+            header('Content-Length: ' . $this->getEstimate());
+            $options = new \ZipStream\Option\Archive();
+            $options->setSendHttpHeaders(true);
+            $options->setEnableZip64(false);
+            $options->setDeflateLevel(-1);
+            $zip = new \ZipStream\ZipStream($this->name, $options);
+
+            $fileOptions = new \ZipStream\Option\File();
+            $fileOptions->setMethod(\ZipStream\Option\Method::STORE());
+            foreach ($this->files as $file) {
+            if ($file['type'] === 'addFile') {
+                $zip->addFile($file['name'], $file['data'], $fileOptions);
+            }
+            if ($file['type'] === 'addFileFromPath') {
+                $zip->addFileFromPath($file['name'], $file['path'], $fileOptions);
+            }
+            }
+            $zip->finish();
+            exit;
+        }
+    }
+
+It only works with the following constraints:
+
+- All file content is known beforehand.
+- Content Deflation is disabled
+
+Thanks to
+`partiellkorrekt <https://github.com/maennchen/ZipStream-PHP/issues/89#issuecomment-1047949274>`_
+for this workaround.

guides/FlySystem.rst

@@ -0,0 +1,33 @@
+Usage with FlySystem
+===============
+
+For saving or uploading the generated zip, you can use the
+`Flysystem <https://flysystem.thephpleague.com>`_ package, and its many
+adapters.
+
+For that you will need to provide another stream than the ``php://output``
+default one, and pass it to Flysystem ``putStream`` method.
+
+.. code-block:: php
+
+    // Open Stream only once for read and write since it's a memory stream and
+    // the content is lost when closing the stream / opening another one
+    $tempStream = fopen('php://memory', 'w+');
+
+    // Init Options
+    $zipStreamOptions = new Archive();
+    $zipStreamOptions->setOutputStream($tempStream);
+
+    // Create Zip Archive
+    $zipStream = new ZipStream('test.zip', $zipStreamOptions);
+    $zipStream->addFile('test.txt', 'text');
+    $zipStream->finish();
+
+    // Store File (see Flysystem documentation, and all its framework integration)
+    $adapter = new Local(__DIR__.'/path/to/folder'); // Can be any adapter (AWS, Google, Ftp, etc.)
+    $filesystem = new Filesystem($adapter);
+
+    $filesystem->putStream('test.zip', $tempStream)
+
+    // Close Stream
+    fclose($tempStream);

guides/Nginx.rst

@@ -0,0 +1,16 @@
+Usage with nginx
+=============
+
+If you are using nginx as a webserver, it will try to buffer the response.
+So you'll want to disable this with a custom header:
+
+.. code-block:: php
+    header('X-Accel-Buffering: no');
+    # or with the Response class from Symfony
+    $response->headers->set('X-Accel-Buffering', 'no');
+
+Alternatively, you can tweak the
+`fastcgi cache parameters <https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_buffers>`_
+within nginx config.
+
+See `original issue <https://github.com/maennchen/ZipStream-PHP/issues/77>`_.

guides/Options.rst

@@ -0,0 +1,61 @@
+Available options
+===============
+
+Here is the full list of options available to you. You can also have a look at
+``src/Option/Archive.php`` file.
+
+First, an instance of ``ZipStream\Option\Archive`` needs to be created, and
+after that you use setters methods to modify the values.
+
+.. code-block:: php
+    use ZipStream\ZipStream;
+    use ZipStream\Option\Archive as ArchiveOptions;
+
+    require_once 'vendor/autoload.php';
+
+    $opt = new ArchiveOptions();
+
+    // Define output stream (argument is of type resource)
+    $opt->setOutputStream($fd);
+
+    // Set the deflate level (default is 6; use -1 to disable it)
+    $opt->setDeflateLevel(6);
+
+    // Add a comment to the zip file
+    $opt->setComment('This is a comment.');
+
+    // Size, in bytes, of the largest file to try and load into memory (used by addFileFromPath()).  Large files may also be compressed differently; see the 'largeFileMethod' option.
+    $opt->setLargeFileSize(30000000);
+
+    // How to handle large files.  Legal values are STORE (the default), or DEFLATE. Store sends the file raw and is significantly faster, while DEFLATE compresses the file and is much, much slower. Note that deflate must compress the file twice and is extremely slow.
+    $opt->setLargeFileMethod(ZipStream\Option\Method::STORE());
+    $opt->setLargeFileMethod(ZipStream\Option\Method::DEFLATE());
+
+    // Send http headers (default is false)
+    $opt->setSendHttpHeaders(false);
+
+    // HTTP Content-Disposition.  Defaults to 'attachment', where FILENAME is the specified filename. Note that this does nothing if you are not sending HTTP headers.
+    $opt->setContentDisposition('attachment');
+
+    // Set the content type (does nothing if you are not sending HTTP headers)
+    $opt->setContentType('application/x-zip');
+
+    // Set the function called for setting headers. Default is the `header()` of PHP
+    $opt->setHttpHeaderCallback('header');
+
+    // Enable streaming files with single read where general purpose bit 3 indicates local file header contain zero values in crc and size fields, these appear only after file contents in data descriptor block. Default is false. Set to true if your input stream is remote (used with addFileFromStream()).
+    $opt->setZeroHeader(false);
+
+    // Enable reading file stat for determining file size. When a 32-bit system reads file size that is over 2 GB, invalid value appears in file size due to integer overflow. Should be disabled on 32-bit systems with method addFileFromPath if any file may exceed 2 GB. In this case file will be read in blocks and correct size will be determined from content. Default is true.
+    $opt->setStatFiles(true);
+
+    // Enable zip64 extension, allowing very large archives (> 4Gb or file count > 64k)
+    // default is true
+    $opt->setEnableZip64(true);
+
+    // Flush output buffer after every write
+    // default is false
+    $opt->setFlushOutput(true);
+
+    // Now that everything is set you can pass the options to the ZipStream instance
+    $zip = new ZipStream('example.zip', $opt);

guides/PSR7Streams.rst

@@ -0,0 +1,18 @@
+Usage with PSR 7 Streams
+===============
+
+PSR-7 streams are `standardized streams <https://www.php-fig.org/psr/psr-7/>`_.
+
+ZipStream-PHP supports working with these streams with the function
+``addFileFromPsr7Stream``. 
+
+For all parameters of the function see the API documentation.
+
+Example
+---------------
+
+.. code-block:: php
+    
+    $stream = $response->getBody();
+    // add a file named 'streamfile.txt' from the content of the stream
+    $zip->addFileFromPsr7Stream('streamfile.txt', $stream);

guides/StreamOutput.rst

@@ -0,0 +1,33 @@
+Stream Output
+===============
+
+Stream to S3 Bucket
+---------------
+
+.. code-block:: php
+    use Aws\S3\S3Client;
+    use Aws\Credentials\CredentialProvider;
+    use ZipStream\Option\Archive;
+    use ZipStream\ZipStream;
+
+    $bucket = 'your bucket name';
+    $client = new S3Client([
+        'region' => 'your region',
+        'version' => 'latest',
+        'bucketName' => $bucket,
+        'credentials' => CredentialProvider::defaultProvider(),
+    ]);
+    $client->registerStreamWrapper();
+
+    $zipFile = fopen("s3://$bucket/example.zip", 'w');
+
+    $options = new Archive();
+    $options->setEnableZip64(false);
+    $options->setOutputStream($zipFile);
+
+    $zip = new ZipStream(null, $options);
+    $zip->addFile('file1.txt', 'File1 data');
+    $zip->addFile('file2.txt', 'File2 data');
+    $zip->finish();
+
+    fclose($zipFile);