Archive Laravel Package

Getting Started

Start by installing the package via Composer:

composer require joomla/archive

The package requires PHP 8.1+ and optional extensions (zlib for .gz, bz2 for .bz2). After installation, you can extract archives with minimal code:

use Joomla\Archive\Archive;

$archive = new Archive(['tmp_path' => sys_get_temp_dir()]);
$archive->extract('/path/to/archive.zip', '/path/to/destination');

No manual adapter selection needed — the package auto-detects archive types (zip, tar, tgz, tbz2, gz, bz2) based on extension and content. This makes it ideal for handling user-uploaded archives, deployment artifacts, or backup restoration.

Implementation Patterns

• Standard extraction workflow: For typical use (e.g., unpacking plugin/extension archives), instantiate Archive with tmp_path and call extract(). Use sys_get_temp_dir() for portability.

• Custom adapter injection: When you need to override default behavior (e.g., for enhanced security, logging, or alternative backends like Phar or external tools), implement \Joomla\Archive\ExtractableInterface and register via setAdapter($type, $className):

$archive = new Archive();
$archive->setAdapter('zip', App\Archives\SecureZipExtractor::class);
$archive->extract('app.zip', 'vendor/');

• Adapter discovery: Use getSupportedAdapters() to introspect available adapters (useful for UI hints or fallback strategies):

$supported = $archive->getSupportedAdapters(); // ['zip', 'tar', 'bz2', 'gz']

• Integration in Laravel: Wrap in a service class or command for Laravel jobs. For example, in an ExtractArchiveJob:

  public function handle()
  {
      $archive = new Archive(['tmp_path' => $this->tempDir]);
      $archive->extract($this->archivePath, $this->destinationPath);
      // Trigger post-extraction events, clean temp files, etc.
  }
  

Gotchas and Tips

• Security: path traversal protection: As of v2.0.1+, the package mitigates CVE-2022-23793 (Tar Zip Slip) and CVE-2021-26028 (untrusted extraction). Still, always validate $destination paths (e.g., ensure they’re within expected app directories) to prevent accidental overwrites.

• Adapters are static: Each adapter class must be stateless — methods like isSupported() and extract() are static. Custom adapters cannot rely on instance state or DI container injection during extraction. Inject dependencies before calling setAdapter() and capture them in closures or static context if absolutely necessary (not recommended).

• Version compatibility: v3.x requires PHP 8.1+, v4.x requires PHP 8.3+. Ensure your target environment matches. Use ~3.0 or ^4.0 in composer.json accordingly.

• Exception handling: Check for \Joomla\Archive\Exception\UnsupportedArchiveException with getUnsupportedAdapterType() for user-friendly messages. Other exceptions (e.g., file not found, permission denied) use standard RuntimeException.

• Performance: v3.0.1+ improved unpacking performance — prefer recent patch versions (e.g., 3.0.4 or 4.0.0). For large archives (>100 MB), consider offloading extraction to queued jobs.

• No compression support: This package only extracts archives; it does not create them. For bundling (e.g., creating .zip of logs), use other tools or libraries like chumper/zipper or symfony/process + zip CLI.