A lightweight image compression library built with Laravel

Kompressor is a Laravel-ready package that compresses uploaded images using Intervention Image and Spatie Image Optimizer, with automatic fallback between imagick and gd.

It provides an easy, fluent API:

$compressed = Kompressor::compress($request->file('image'));

Features

• Automatic driver selection (imagick → gd)
• Compress images to a target max size (KB)
• Optimizes using external binaries when available
• Stores original + compressed versions
• Laravel Storage-ready
• Zero configuration required (auto-publishes config)

Installation

Install via Composer

composer require jessyledama/kompressor

Dependencies

Kompressor depends on these packages:

Laravel packages (installed automatically)

Package	Purpose
intervention/image	Image manipulation (GD/Imagick)
spatie/image-optimizer	Lossless optimization

If they are not installed automatically, run:

composer require intervention/image spatie/image-optimizer

System Dependencies

Spatie/ImageOptimizer uses external binaries (optional but highly recommended) for best compression speed & quality.

Ubuntu / Debian

sudo apt install jpegoptim optipng pngquant gifsicle webp

CentOS / AlmaLinux

sudo yum install epel-release
sudo yum install jpegoptim optipng pngquant gifsicle libwebp-tools

macOS (Homebrew)

brew install jpegoptim optipng pngquant gifsicle webp

Publish Config (optional)

If you want to customize the directories or max allowed size:

php artisan vendor:publish --tag=kompressor-config

This creates:

config/kompressor.php

Example:

return [
    'original_path'   => 'original-images',
    'compressed_path' => 'compressed-images',
    'max_kb'          => 300, // target size in KB
];

Usage

Basic Example (Controller)

use Kompressor;
use Illuminate\Http\Request;

public function store(Request $request)
{
    $validated = $request->validate([
        'image' => ['required', 'mimes:jpg,jpeg,png,gif'],
    ]);

    $compressed = Kompressor::compress($request->file('image'));

    // Example return:
    // [
    //     "original" => "original-images/abc123.jpg",
    //     "compressed" => "compressed-images/compressed_abc123.jpg",
    //     "final_size_kb" => 152,
    //     "driver_used" => "imagick"
    // ]

    $path = $compressed['compressed'];

    // Save to DB, etc...
}

Returned Data Structure

Kompressor returns an array:

[
    'original'       => 'original-images/filename.jpg',
    'compressed'     => 'compressed-images/compressed_filename.jpg',
    'final_size_kb'  => 120.45,
    'driver_used'    => 'imagick'
]

Using in Blade

<img src="{{ asset('storage/' . $compressed['compressed']) }}">

Custom Max Size

Edit config/kompressor.php:

'max_kb' => 200,

Driver Fallback Logic

Kompressor checks in order:

State	Action
imagick installed	Uses Imagick (fastest & cleanest)
imagick missing	Logs warning + uses GD

Development Instructions

Clone the repo:

git clone https://github.com/jessyledama/kompressor.git

Install dependencies:

composer install

License

This package is open-source software licensed under the MIT License.

Contributions

Pull requests and issues are welcome on the Github repo!