ZipStream-PHP

The ZipStream\Stream\CallbackStreamWrapper::open() method allows you to intercept the ZIP data stream via a callback function. This is useful for:

• Streaming to multiple destinations simultaneously (e.g., echoing to the browser while writing to a file).
• Progress tracking by monitoring the length of the $data chunks.
• Custom logging or data transformation.

Note: When using a custom outputStream via a callback, you should set sendHttpHeaders: false in the ZipStream constructor to prevent the library from automatically sending HTTP headers, as you are now manually controlling the output flow.

Important Recommendation: For data transformations (like encoding), prefer using PHP's built-in stream filters via stream_filter_append() rather than performing transformations inside the callback. Stream filters are more efficient and maintain better data integrity.

use ZipStream\ZipStream;
use ZipStream\Stream\CallbackStreamWrapper;

// Example: Stream to multiple destinations
$backupFile = fopen('backup.zip', 'wb');
$logFile = fopen('transfer.log', 'ab');

$zip = new ZipStream(
    outputStream: CallbackStreamWrapper::open(function (string $data) use ($backupFile, $logFile) {
        // Send to browser
        echo $data;
        
        // Save to file efficiently
        fwrite($backupFile, $data);
        
        // Log transfer progress
        fwrite($logFile, "Transferred " . strlen($data) . " bytes\n");
    }),
    sendHttpHeaders: false,
);

$zip->addFile('hello.txt', 'Hello World!');
$zip->finish();

fclose($backupFile);
fclose($logFile);

When using ZipStream within Symfony controller actions, you must wrap your ZipStream logic inside Symfony's StreamedResponse. This ensures that the output is streamed correctly to the user's browser and prevents the generation of corrupted ZIP files.

To implement this, pass a callback to the StreamedResponse constructor. Inside this callback, initialize your ZipStream\ZipStream instance and call its streaming methods (such as addFile, addFileFromPath, or addFileFromStream). Finally, call $zip->finish() to complete the archive within the callback.

use Symfony\Component\HttpFoundation\StreamedResponse;
use ZipStream\ZipStream;

$response = new StreamedResponse(function() {
    $zip = new ZipStream\ZipStream(
        outputName: 'test.zip',
        defaultEnableZeroHeader: true,
        contentType: 'application/octet-stream',
    );

    // ... add files using $zip->addFile() etc.

    $zip->finish();
});

return $response;

To provide a Content-Length header for a ZIP stream, you must use a two-pass approach called 'Simulation'. This involves configuring the ZipStream with an operationMode of either OperationMode::SIMULATE_STRICT or OperationMode::SIMULATE_LAX.

1. SIMULATE_STRICT: Prevents the library from reading the entire file to calculate size. This is useful for ensuring that size calculation remains efficient and doesn't accidentally consume large amounts of memory or time by reading unbuffered data.
2. SIMULATE_LAX: Allows the library to read the entire file if necessary to determine the size.

Workflow:

1. Initialize ZipStream with the chosen simulation mode.
2. Add files to the stream (use addFileFromCallback with exactSize for deferred file opening).
3. Call $zip->finish() to calculate the resulting ZIP file size.
4. Send the Content-Length header to the client.
5. Call $zip->executeSimulation() to perform the actual streaming of the ZIP data.

use ZipStream\OperationMode;
use ZipStream\ZipStream;

$zip = new ZipStream(
    operationMode: OperationMode::SIMULATE_STRICT, // or SIMULATE_LAX
    defaultEnableZeroHeader: false,
    sendHttpHeaders: true,
    outputStream: $stream,
);

// Normally add files
$zip->addFile('sample.txt', 'Sample String Data');

// Use addFileFromCallback and exactSize if you want to defer opening of
// the file resource
$zip->addFileFromCallback(
    'sample.txt',
    exactSize: 18,
    callback: function () {
        return fopen('...');
    }
);

// Read resulting file size
$size = $zip->finish();

// Tell it to the browser
header('Content-Length: '. $size);

// Execute the Simulation and stream the actual zip to the client
$zip->executeSimulation();