Zipstream Php Laravel Package

Getting Started

Install via Composer: composer require maennchen/zipstream-php. Begin by instantiating ZipStream\ZipStream with an output stream (e.g., fopen('php://output', 'w')), then add files using addFile() or addFileFromPath(). For immediate browser download, set proper headers before streaming:

header('Content-Type: application/zip');
header('Content-Disposition: attachment; filename="archive.zip"');
$zip = new ZipStream\ZipStream(fopen('php://output', 'wb'));
$zip->addFile('readme.txt', 'Hello, world!');
$zip->finish();

The earliest success case: generating a ZIP on-the-fly without writing to disk.

Implementation Patterns

• Streaming large datasets: Append files iteratively (e.g., inside a loop) without buffering in memory—ideal for exporting large DB result sets or file collections.
• Dynamic filenames & compression: Use addFile() with custom filenames, and optional ZipStream\Option\Method::DEFLATE() for compression.
• Integration with Symfony/Laravel responses: Stream directly into a Symfony StreamedResponse for clean controller usage:

  $response = new StreamedResponse(function () use ($zip) {
      $zip->addFile('report.csv', $csvContent);
      $zip->finish();
  });
  $response->headers->set('Content-Type', 'application/zip');
  return $response;
  

• Directory support: Add entire directories via addDirectory('folder/'), preserving internal path structure.
• Memory efficiency: Prefer addFileFromPath() for large files to avoid loading them into memory.

Gotchas and Tips

• Output buffering: Disable output_buffering in php.ini or use while (ob_get_level()) ob_end_flush();—ZIP streaming fails silently with buffering active.
• Header timing: Call header() before $zip->finish()—any output (including whitespace) prior causes corruption or "headers already sent" errors.
• Filename encoding: ZIP spec doesn’t enforce UTF-8; use ZipStream\Option\FileName::UTF8() to ensure non-ASCII filenames render correctly.
• Memory limits: Though streaming avoids full-archive buffering, ZipStream\Option\Method::STORE() (no compression) reduces CPU overhead for large binary files.
• Error handling: Wrap $zip->finish() in try/catch—exceptions may surface late (e.g., disk full during final write).
• Testing: Stub the output stream with fopen('php://memory', 'c+') for unit tests without side effects.
• ZIP64 support: Enabled by default; avoid disabling unless targeting legacy systems (set ZipStream\Option\GlobalOption::enableZip64(false) cautiously).