selective/zip-responder

A ZIP responder (PSR-7).

Table of Contents

• Requirements
• Installation
• Usage
  • Sending a ZIP file
  • Sending a ZIP file from a string
  • Sending a ZIP stream
  • Sending a ZipArchive file
  • Sending a ZipStream-PHP archive
  • Sending a PhpZip archive
• Slim 4 Integration

Requirements

• PHP 7.3+ or 8.0+
• A PSR-7 StreamFactory implementation, e.g. nyholm/psr7

Installation

composer require selective/zip-responder

Usage

Creating a new ZipResponder instance using the nyholm/psr7 Psr17Factory:

use Selective\Http\Zip\ZipResponder;
use Nyholm\Psr7\Factory\Psr17Factory;

$zipResponder = new ZipResponder(new Psr17Factory());

Creating a new ZipResponder instance using the slim/psr7 StreamFactory:

use Selective\Http\Zip\ZipResponder;
use Slim\Psr7\Factory\StreamFactory;

$zipResponder = new ZipResponder(new StreamFactory());

Sending a ZIP file

Send ZIP file to browser, force direct download:

return $zipResponder->withZipFile($response, 'source.zip', 'output.zip');

Sending a ZIP file from a string

return $zipResponder->withZipString($response, file_get_contents('example.zip'), 'output.zip');

Sending a ZIP stream

Send ZIP stream to the browser, force direct download:

$stream = fopen('test.zip', 'r');
 
return $zipResponder->withZipStream($response, $stream, 'output.zip');

Sending a ZIP stream on the fly

Sending a file directly to the client is not intended according to the PSR-7 specification, but can still be realized with the help of a CallbackStream.

use Selective\Http\Zip\Stream\CallbackStream;

$callbackStream = new CallbackStream(function () {
    echo 'my binary zip content';
}

$response = $zipResponder->withZipHeaders($response, $outputName, true);

return $response->withBody($callbackStream);

Sending a ZipArchive file

The ZIP extension enables you to transparently read or write ZIP compressed archives and the files inside them. A ZipArchive does not support "memory mapped files", like PHP streams. You can only access local files with ZipArchive. For this purpose, you can create a temporary file, or you can use an existing file from the filesystem.

use ZipArchive;
// ...

// Create temporary filename
$filename = tempnam(sys_get_temp_dir(), 'zip');

// Add files to temporary ZIP file
$zip = new ZipArchive();
$zip->open($filename, ZipArchive::CREATE | ZipArchive::OVERWRITE);
$zip->addFromString('test.txt', 'my content');
$zip->close();

// Render ZIP file into the response as stream
return $zipResponder->withZipStream($response, fopen($filename, 'r'), 'download.zip');

Sending a ZipStream-PHP archive

ZipStream-PHP is a library for streaming dynamic ZIP files without writing to the disk. You can send the file directly to the user, which is much faster and improves testability.

Installation:

composer require maennchen/zipstream-php

Creating and sending a ZIP file (only in-memory) to the browser:

use ZipStream\ZipStream;

// ...

// Create ZIP file, only in-memory
$stream = fopen('php://memory', 'w+b');

$zip = new ZipStream(
    outputStream: $stream,
    // disable output of HTTP headers
    sendHttpHeaders: false,
);

// create a file named 'hello.txt'
$zip->addFile(
    fileName: 'hello.txt',
    data: 'This is the contents of hello.txt',
);

$zip->finish();

$response = $zipResponder->withZipStream($response, $stream, 'download.zip');

Sending a ZIP-stream on the fly:

use Selective\Http\Zip\Stream\CallbackStream;
use ZipStream\ZipStream;
//...

$callbackStream = new CallbackStream(function () {
    // Flush ZIP file directly to output stream (php://output)
    $zip = new ZipStream(
        flushOutput: true,
        sendHttpHeaders: false,
    );

    // Add files to ZIP file and stream it directly
    $zip->addFile('test.txt', 'my file content');
    $zip->addFile('test2.txt', 'my file content 2');
    $zip->addFile('test3.txt', 'my file content 4');
    $zip->finish();
});

$response = $zipResponder->withZipHeaders($response, $outputName, true);

return $response->withBody($callbackStream);

Sending a PhpZip archive

PhpZip is a library for extended work with ZIP-archives.

Installation:

composer require nelexa/zip

Note, when you use the nelexa/zip component, you may not need the selective/zip-responder component because the nelexa/zip already provides its own PSR-7 responder.

Example

use PhpZip\ZipFile;

// ...

$zipFile = new ZipFile();
$zipFile->addFromString('test.txt', 'File content');

return $zipFile->outputAsResponse($response, 'download.zip');

In case you want to keep your architecture more clean (SRP), you may use the selective/zip-responder responder to create and send a ZIP file to the browser as follows:

use PhpZip\ZipFile;

// ...

// Create new archive
$zipFile = new ZipFile();

// Add entry from string
$zipFile->addFromString('test.txt', 'File content');
     
return $zipResponder->withZipString($response, $zipFile->outputAsString(), 'download.zip');

Slim 4 Integration

Create a DI container definition for: StreamFactoryInterface::class and ZipResponder::class

A nyholm/psr7 and PHP-DI example:

<?php

use Nyholm\Psr7\Factory\Psr17Factory;
use Psr\Container\ContainerInterface;
use Psr\Http\Message\StreamFactoryInterface;
use Selective\Http\Zip\ZipResponder;

return [
    // ...

    StreamFactoryInterface::class => function (ContainerInterface $container) {
        return $container->get(Psr17Factory::class);
    },

    ZipResponder::class => function (ContainerInterface $container) {
        return new ZipResponder($container->get(StreamFactoryInterface::class));
    },
];

A slim/psr7 and PHP-DI example:

<?php

use Psr\Container\ContainerInterface;
use Psr\Http\Message\StreamFactoryInterface;
use Slim\Psr7\Factory\StreamFactory;
use Selective\Http\Zip\ZipResponder;

return [
    // ...
    
    StreamFactoryInterface::class => function () {
        return new StreamFactory();
    },
    
    ZipResponder::class => function (ContainerInterface $container) {
        return new ZipResponder($container->get(StreamFactoryInterface::class));
    },
];

The responder should only be used within an action handler or middleware.

Action class example using dependency injection:

<?php

namespace App\Action;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Selective\Http\Zip\ZipResponder;
use ZipArchive;

final class ZipDemoAction
{
    /**
     * @var ZipResponder
     */
    private $zipResponder;

    public function __construct(ZipResponder $zipResponder)
    {
        $this->zipResponder = $zipResponder;
    }

    public function __invoke(
        ServerRequestInterface $request, 
        ResponseInterface $response
    ): ResponseInterface {
        $filename = tempnam(sys_get_temp_dir(), 'zip');

        $zip = new ZipArchive();
        $zip->open($filename, ZipArchive::CREATE | ZipArchive::OVERWRITE);
        $zip->addFromString('test.txt', 'my content');
        $zip->close();

        return $this->zipResponder->withZipFile($response, $filename, 'filename.zip');
    }
}

License

The MIT License (MIT). Please see License File for more information.