From 75160b12821f7f4299cce7f0b69c83c1502ae071 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Anton=20Luka=20=C5=A0ijanec?= <anton@sijanec.eu>
Date: Mon, 27 May 2024 13:08:29 +0200
Subject: 2024-02-19 upstream

---
 vendor/maennchen/zipstream-php/guides/Symfony.rst | 126 ++++++++++++++++++++++
 1 file changed, 126 insertions(+)
 create mode 100644 vendor/maennchen/zipstream-php/guides/Symfony.rst

(limited to 'vendor/maennchen/zipstream-php/guides/Symfony.rst')

diff --git a/vendor/maennchen/zipstream-php/guides/Symfony.rst b/vendor/maennchen/zipstream-php/guides/Symfony.rst
new file mode 100644
index 0000000..18f9059
--- /dev/null
+++ b/vendor/maennchen/zipstream-php/guides/Symfony.rst
@@ -0,0 +1,126 @@
+Usage with Symfony
+===============
+
+Overview for using ZipStream in Symfony
+--------
+
+Using ZipStream in Symfony requires use of Symfony's ``StreamedResponse`` when
+used in controller actions.
+
+Wrap your call to the relevant ``ZipStream`` stream method (i.e. ``addFile``,
+``addFileFromPath``, ``addFileFromStream``) in Symfony's ``StreamedResponse``
+function passing in any required arguments for your use case.
+
+Using Symfony's ``StreamedResponse`` will allow Symfony to stream output from
+ZipStream correctly to users' browsers and avoid a corrupted final zip landing
+on the users' end.
+
+Example for using ``ZipStream`` in a controller action to zip stream files
+stored in an AWS S3 bucket by key:
+
+.. code-block:: php
+
+    use Symfony\Component\HttpFoundation\StreamedResponse;
+    use Aws\S3\S3Client;
+    use ZipStream;
+
+    //...
+
+    /**
+    * @Route("/zipstream", name="zipstream")
+    */
+    public function zipStreamAction()
+    {
+        //sample test file on s3
+        $s3keys = array(
+        "ziptestfolder/file1.txt"
+        );
+
+        $s3Client = $this->get('app.amazon.s3'); //s3client service
+        $s3Client->registerStreamWrapper(); //required
+
+        //using StreamedResponse to wrap ZipStream functionality for files on AWS s3.
+        $response = new StreamedResponse(function() use($s3keys, $s3Client)
+        {
+            // Define suitable options for ZipStream Archive.
+            $options = new \ZipStream\Option\Archive();
+            $options->setContentType('application/octet-stream');
+            // this is needed to prevent issues with truncated zip files
+            $options->setZeroHeader(true);
+            $options->setComment('test zip file.');
+
+            //initialise zipstream with output zip filename and options.
+            $zip = new ZipStream\ZipStream('test.zip', $options);
+
+            //loop keys - useful for multiple files
+            foreach ($s3keys as $key) {
+                // Get the file name in S3 key so we can save it to the zip
+                //file using the same name.
+                $fileName = basename($key);
+
+                //concatenate s3path.
+                $bucket = 'bucketname'; //replace with your bucket name or get from parameters file.
+                $s3path = "s3://" . $bucket . "/" . $key;
+
+                //addFileFromStream
+                if ($streamRead = fopen($s3path, 'r')) {
+                $zip->addFileFromStream($fileName, $streamRead);
+                } else {
+                die('Could not open stream for reading');
+                }
+            }
+
+            $zip->finish();
+
+        });
+
+        return $response;
+    }
+
+In the above example, files on AWS S3 are being streamed from S3 to the Symfon
+application via ``fopen`` call when the s3Client has ``registerStreamWrapper``
+applied. This stream is then passed to ``ZipStream`` via the
+``addFileFromStream`` function, which ZipStream then streams as a zip to the
+client browser via Symfony's ``StreamedResponse``. No Zip is created server
+side, which makes this approach a more efficient solution for streaming zips to
+the client browser especially for larger files.
+
+For the above use case you will need to have installed
+`aws/aws-sdk-php-symfony <https://github.com/aws/aws-sdk-php-symfony>`_ to
+support accessing S3 objects in your Symfony web application. This is not
+required for locally stored files on you server you intend to stream via
+``ZipStream``.
+
+See official Symfony documentation for details on
+`Symfony's StreamedResponse <https://symfony.com/doc/current/components/http_foundation.html#streaming-a-response>`_ 
+``Symfony\Component\HttpFoundation\StreamedResponse``.
+
+Note from `S3 documentation <https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/s3-stream-wrapper.html>`_:
+
+    Streams opened in "r" mode only allow data to be read from the stream, and
+    are not seekable by default. This is so that data can be downloaded from
+    Amazon S3 in a truly streaming manner, where previously read bytes do not
+    need to be buffered into memory. If you need a stream to be seekable, you
+    can pass seekable into the stream context options of a function.
+
+Make sure to configure your S3 context correctly!
+
+Uploading a file
+--------
+
+You need to add correct permissions
+(see `#120 <https://github.com/maennchen/ZipStream-PHP/issues/120>`_)
+
+**example code**
+
+
+.. code-block:: php
+
+    $path = "s3://{$adapter->getBucket()}/{$this->getArchivePath()}";
+
+    // the important bit
+    $outputContext = stream_context_create([
+        's3' => ['ACL' => 'public-read'],
+    ]);
+
+    fopen($path, 'w', null, $outputContext);
\ No newline at end of file
-- 
cgit v1.2.3