README

Automatically compress images, PDFs and videos on upload in Laravel. Auto-detects the MIME type and applies the right compressor — zero config needed.

Requirements

• PHP 8.2+
• Laravel 11 or 12
• GD extension (default) or Imagick
• Optional: Ghostscript (gs) for PDF compression
• Optional: FFmpeg (ffmpeg) for video compression

Installation

composer require justsmiletoo/laravel-file-compressor

The service provider is auto-discovered. To publish the config file:

php artisan vendor:publish --tag=file-compressor-config

System binaries (optional)

For PDF compression, install Ghostscript:

# Alpine (Docker)
apk add ghostscript

# Ubuntu/Debian
apt-get install ghostscript

# macOS
brew install ghostscript

For video compression, install FFmpeg:

# Alpine (Docker)
apk add ffmpeg

# Ubuntu/Debian
apt-get install ffmpeg

# macOS
brew install ffmpeg

Usage

Auto-detect and compress

The compress() method detects the file type and delegates to the right compressor:

use JustSmileToo\FileCompressor\FileCompressor;

// From an UploadedFile (typical controller usage)
$result = app(FileCompressor::class)->compress($request->file('avatar'));

// From a file path
$result = app(FileCompressor::class)->compress('/path/to/file.jpg');

// Using the facade
use JustSmileToo\FileCompressor\Facades\FileCompressor;

$result = FileCompressor::compress($uploadedFile);

Type-specific methods

Skip MIME detection and call a compressor directly:

$result = FileCompressor::compressImage($file);
$result = FileCompressor::compressPdf($file);
$result = FileCompressor::compressVideo($file);

Presets

Use named presets for common image use cases:

// Uses the 'avatar' preset: 200x200, cover mode, quality 80
$result = FileCompressor::compressImage($file, ['preset' => 'avatar']);

// Uses 'banner' preset: 1920xAuto, scale mode, quality 85
$result = FileCompressor::compressImage($file, ['preset' => 'banner']);

// Override a preset value
$result = FileCompressor::compressImage($file, [
    'preset' => 'avatar',
    'max_width' => 300,
    'max_height' => 300,
]);

Define your own presets in the config:

// config/file-compressor.php
'image' => [
    'presets' => [
        'avatar' => ['max_width' => 200, 'max_height' => 200, 'mode' => 'cover', 'quality' => 80],
        'thumbnail' => ['max_width' => 300, 'max_height' => 300, 'mode' => 'cover', 'quality' => 80],
        'banner' => ['max_width' => 1920, 'max_height' => 600, 'mode' => 'scale', 'quality' => 85],
        'receipt' => ['max_width' => 1200, 'mode' => 'scale', 'quality' => 80, 'convert_to' => 'webp'],
    ],
],

Resize modes

• scale (default) — Proportionally scale down. Never upscales. Aspect ratio preserved.
• cover — Crop and resize to fill exact dimensions (like CSS object-fit: cover).

// Scale down proportionally
$result = FileCompressor::compressImage($file, ['mode' => 'scale']);

// Crop to exact 200x200
$result = FileCompressor::compressImage($file, [
    'max_width' => 200,
    'max_height' => 200,
    'mode' => 'cover',
]);

Per-call options

Override config values for a single call:

// Smaller avatar with WebP conversion
$result = FileCompressor::compressImage($file, [
    'max_width' => 400,
    'max_height' => 400,
    'quality' => 70,
    'convert_to' => 'webp',
]);

// High-quality PDF
$result = FileCompressor::compressPdf($file, [
    'quality' => 'printer', // screen, ebook, printer, prepress
]);

// Lower quality video for previews
$result = FileCompressor::compressVideo($file, [
    'crf' => 32,
    'max_width' => 720,
    'preset' => 'fast',
]);

CompressionResult

Every compression call returns a CompressionResult DTO:

$result = FileCompressor::compress($file);

$result->path;              // string — path to the compressed file
$result->originalSize;      // int — original file size in bytes
$result->compressedSize;    // int — compressed file size in bytes
$result->mimeType;          // string — MIME type of the output
$result->wasCompressed;     // bool — false if compression was skipped or didn't reduce size
$result->savedBytes();      // int — bytes saved
$result->savedPercentage(); // float — e.g. 65.42

Integration example

Typical usage in a file upload service:

use Illuminate\Http\UploadedFile;
use Illuminate\Support\Facades\Storage;
use JustSmileToo\FileCompressor\FileCompressor;

class FileUploadService
{
    public function __construct(
        private FileCompressor $compressor,
    ) {}

    public function upload(UploadedFile $file, string $directory): string
    {
        $result = $this->compressor->compress($file);

        $filename = uniqid() . '.' . $file->getClientOriginalExtension();

        if ($result->wasCompressed) {
            return Storage::disk('public')->putFileAs(
                $directory,
                new \Illuminate\Http\File($result->path),
                $filename,
            );
        }

        return $file->storeAs($directory, $filename, 'public');
    }
}

Check support

FileCompressor::isSupported('image/jpeg'); // true
FileCompressor::isSupported('text/plain'); // false
FileCompressor::isEnabled();               // true (unless disabled in config)

Configuration

All values can be overridden via environment variables. See config/file-compressor.php for the full list.

Handling unsupported files

If a file type is not supported, compress() throws UnsupportedFileTypeException. You can check support beforehand:

use JustSmileToo\FileCompressor\Exceptions\UnsupportedFileTypeException;

if (FileCompressor::isSupported($file->getMimeType())) {
    $result = FileCompressor::compress($file);
} else {
    // Store without compression
}

Or catch the exception:

try {
    $result = FileCompressor::compress($file);
} catch (UnsupportedFileTypeException) {
    // File type not supported, store as-is
}

Temp file cleanup

Compressed files are written to the configured temp_dir. After storing the compressed file to your disk, the temp file can be safely deleted. The OS will also clean up temp files periodically.

Testing

composer test

Place test fixtures (sample.jpg, sample.pdf, sample.mp4) in tests/Fixtures/ to enable all tests.

License

MIT. See LICENSE.