diff options
Diffstat (limited to 'vendor/maennchen/zipstream-php/guides/Symfony.rst')
| -rw-r--r-- | vendor/maennchen/zipstream-php/guides/Symfony.rst | 126 |
1 files changed, 126 insertions, 0 deletions
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 |