Php Archive Laravel Package

Getting Started

Install with Composer: composer require splitbrain/php-archive. Start by reading or extracting simple archives—no configuration needed. The library exposes Splitbrain\PHP\Archive\Tar and Splitbrain\PHP\Archive\Zip as primary classes. A minimal first use:

$tar = new Splitbrain\PHP\Archive\Tar('archive.tar.gz');
$contents = $tar->listContents(); // See what’s inside
$tar->extract('important.txt', storage_path('app/temp'));

Use this when you need archive access without relying on zip/tar binaries or ext-zip—ideal for shared hosting or containerized environments with minimal extensions.

Implementation Patterns

• Streaming-first: Open archives from strings or streams instead of filenames for memory efficiency and integration with Laravel’s Storage facade:

  $archiveData = Storage::disk('s3')->get('backups/app.tar');
  $tar = new Splitbrain\PHP\Archive\Tar();
  $tar->open($archiveData);
  $tar->each(function($entry) {
      if ($entry['type'] === 'file') {
          Storage::disk('local')->put($entry['name'], $entry['data']);
      }
  });
  

• Incremental ZIP creation (e.g., for plugin bundles or deployment artifacts):

  $zip = new Splitbrain\PHP\Archive\Zip('build.zip', true); // overwrite = true
  $zip->addFile(resource_path('icon.png'), 'icon.png');
  $zip->addString(json_encode(['version' => '1.0']), 'manifest.json');
  $zip->addDirectory('resources/views', 'views'); // Adds recursively
  $zip->close(); // Critical!
  

• Integrate into Artisan commands for build-time packaging:

  // In a custom command's handle()
  $zip = new Splitbrain\PHP\Archive\Zip($this->outputPath, true);
  foreach ($this->getFilesToBundle() as $file) {
      $zip->addFile($file, str_replace(base_path(), '', $file));
  }
  $zip->close();
  

• Prefer Zip over Tar when distributing to Windows users or when cross-platform compatibility is non-negotiable.

Gotchas and Tips

• Always call close() on Zip instances—archives written without it will be unreadable/corrupt. Tar is more forgiving but still safer with explicit close or write.
• Zip-slip risk: Never extract $entry['name'] directly without sanitizing paths (e.g., basename() or verify relative paths never escape the target dir).
• Metadata limitations: Permissions (mode) and timestamps are preserved within archives, but extracted files may lose execute bits on non-Unix systems. Don’t rely on this for security-critical workflows.
• Memory usage: For large archives (>100MB), prefer streaming (pass a resource or Stringable to open()) instead of filenames—Laravel’s Storage::readStream() works well here.
• Namespace conflicts: PHP’s phar:// stream wrapper can interfere. Use fully qualified class names (\Splitbrain\PHP\Archive\Zip) or ensure phar extension is disabled in prod.
• Performance warning: Pure-PHP parsing is ~3–5× slower than ext-zip. Profile with real workloads—avoid in request cycle for user uploads; better suited for async jobs (e.g., queued backup generation).