Zipper Laravel Package

Getting Started

• Install into a legacy Laravel app only after confirming framework/PHP compatibility:

composer require chumper/zipper

• Ensure PHP’s zip extension is enabled (php -m | grep zip). This package is a thin wrapper around ZipArchive; without ext-zip it will fail immediately.
• On Laravel <5.5, register the provider and facade manually in config/app.php:

'providers' => [
    Chumper\Zipper\ZipperServiceProvider::class,
],

'aliases' => [
    'Zipper' => Chumper\Zipper\Facades\Zipper::class,
],

Laravel 5.5+ may auto-discover it, but verify before relying on the facade alias.

• Look first at vendor/chumper/zipper/src/Chumper/Zipper/Zipper.php for the actual API. The README is old; the class is the source of truth.
• First practical use case: build a zip from generated export files and return it as a download.

use Chumper\Zipper\Facades\Zipper;
use Illuminate\Support\Facades\File;

$dir = storage_path('app/exports');
File::ensureDirectoryExists($dir);

$zipPath = $dir.'/orders-'.now()->format('YmdHis').'.zip';

Zipper::make($zipPath)
    ->add([storage_path('app/exports/orders.csv')])
    ->close();

return response()->download($zipPath)->deleteFileAfterSend(true);

If you only need a one-off zip, native ZipArchive is usually clearer. Use this package when you want its chained API or already have legacy code depending on it.

Implementation Patterns

• Wrap the package in a small application service rather than scattering the facade throughout controllers. Because the package is archived, isolation makes replacement easier later.

final class OrderArchive
{
    public function build(array $files, string $zipPath): string
    {
        Zipper::make($zipPath)
            ->add($files)
            ->close();

        return $zipPath;
    }
}

• Use chaining for directory structure inside the archive. Call close() explicitly, even when chaining:

Zipper::make($zipPath)
    ->folder('reports')
    ->add($reportPath)
    ->folder('invoices')
    ->add($invoicePaths)
    ->close();

• Generate small files in memory with addString() rather than writing temporary files:

Zipper::make($zipPath)
    ->addString('manifest.json', json_encode($manifest, JSON_PRETTY_PRINT))
    ->close();

• For extraction, extract to a temporary directory first, validate the resulting paths, then move only expected files into permanent storage:

$tmp = storage_path('app/tmp/'.Str::uuid());
File::ensureDirectoryExists($tmp);

Zipper::make($uploadedZipPath)->extractTo($tmp);

• Integrate with Laravel Storage by resolving local paths first. Zipper expects filesystem paths, not Storage URLs or S3 keys:

$local = Storage::disk('local')->path('exports/orders.csv');

Zipper::make($zipPath)->add($local)->close();

For remote disks, download to a temp local path, build the archive, upload it, then delete the temp files.

• Queue large archive jobs. Zipping hundreds of files in a request is a common timeout source; use a job, write the zip to storage/app, and notify or expose a download route when finished.

• In tests, use Storage::fake() and inspect the generated archive with native ZipArchive rather than only asserting the file exists:

$zip = new ZipArchive();
$zip->open($zipPath);
$this->assertNotFalse($zip->locateName('reports/orders.csv'));
$zip->close();

Gotchas and Tips

• Archived and unsupported. Last release was 2020. Treat it as legacy-only. It is not a good choice for new Laravel 10/11 projects; prefer native ZipArchive, nelexa/zip, maennchen/zipstream-php for streaming, or a maintained fork such as zanysoft/laravel-zip.
• Always call close(). Forgetting it can leave the archive incomplete or leave file handles open, especially on Windows.
• Existing archives are easy to mis-handle. If you expect a fresh archive, delete the target path first. Opening an existing zip and adding files can append rather than replace, depending on the call path and version.
• Control internal paths. Passing absolute source paths can produce unexpected names inside the archive. Use folder() and verify with listFiles() in a test.
• Zip-slip is real. Never extract untrusted archives directly into a web root or application directory. Sanitize entry names and reject ../ traversal after extraction.
• Errors may be silent. The wrapper does not consistently throw on ZipArchive failures. Check that the zip exists, inspect listFiles(), and validate extracted files. Wrap archive operations in try/finally for temp cleanup.
• Memory and time limits. Large files and many entries can exhaust memory or hit max_execution_time. Queue the work and set sensible limits.
• Config cache and aliases. After publishing or changing config, run php artisan config:cache. Facade alias conflicts are possible in apps that already define Zipper.
• Pin the version. Since there will be no fixes, lock the exact package version in composer.lock and avoid broad constraints. Plan a replacement path before the next Laravel/PHP upgrade.