Search by

christyoga123 / image-optimizer

ChristYoga123

A fluent Laravel package for optimizing images - resize, convert formats (WebP, JPG, PNG, AVIF), and reduce file size while maintaining quality

Package info

github.com/ChristYoga123/image-optimizer

Homepage

pkg:composer/christyoga123/image-optimizer

Statistics

Installs: 1 298

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v2.0.0 2026-11-04 10:26 UTC

This package is auto-updated.

Last update: 2026-11-04 10:27:03 UTC


README

A fluent Laravel package for optimizing images - resize, convert formats (WebP, JPG, PNG, AVIF), and reduce file size while maintaining quality.

Latest Version on Packagist License

Features

  • ๐Ÿ–ผ๏ธ Format Conversion - Convert images to WebP, JPG, PNG, GIF, AVIF
  • ๐Ÿ“ Smart Resize - Resize with max width/height while maintaining aspect ratio
  • ๐ŸŽš๏ธ Quality Control - Adjustable quality settings for optimal file size
  • ๐Ÿ”ง Fluent API - Chain methods for clean, readable code
  • โš™๏ธ Configurable - Publish and customize default settings
  • ๐Ÿงน Cleanup - Manual or opt-in automatic temporary file cleanup
  • ๐Ÿ›ก๏ธ Secure by default - Format whitelist, decompression-bomb guard, EXIF/GPS stripping, random temp names

Requirements

  • PHP 8.1+
  • Laravel 10.x, 11.x, 12.x, or 13.x
  • GD Library or Imagick extension

Installation

Install the package via Composer:

composer require christyoga123/image-optimizer

The package will automatically register its service provider.

Publish Configuration (Optional)

php artisan vendor:publish --tag=image-optimizer-config

This will create a config/image-optimizer.php file with all available options.

Usage

Basic Usage

use Christyoga123\ImageOptimizer\ImageOptimizer;

// Process uploaded file and get optimized temp path
$tempPath = ImageOptimizer::make()
    ->toWebp()
    ->maxDimensions(1200, 1200)
    ->quality(85)
    ->process($uploadedFile);

// Do something with the optimized file
Storage::disk('public')->put('images/photo.webp', file_get_contents($tempPath));

// Remove the temp file when you're done
@unlink($tempPath);

Using Facade

use Christyoga123\ImageOptimizer\Facades\ImageOptimizer;

$tempPath = ImageOptimizer::make()
    ->toWebp()
    ->maxWidth(800)
    ->process($request->file('image'));

From Request Input

$tempPath = ImageOptimizer::make()
    ->toJpg()
    ->quality(90)
    ->processFromRequest('photo');

if ($tempPath) {
    // File was uploaded and processed
    $user->update(['avatar' => Storage::putFile('avatars', $tempPath)]);
}

From File Path

$tempPath = ImageOptimizer::make()
    ->toPng()
    ->maxDimensions(600, 600)
    ->processFromPath('/path/to/original/image.jpg');

With Default Settings

Apply all defaults from config at once:

$tempPath = ImageOptimizer::make()
    ->withDefaults()
    ->process($uploadedFile);

Get Size Comparison

$optimizer = ImageOptimizer::make()
    ->toWebp()
    ->quality(80)
    ->maxDimensions(1200, 1200);

$tempPath = $optimizer->process($uploadedFile);

$comparison = $optimizer->getSizeComparison($uploadedFile->getRealPath());

// Result:
// [
//     'original_size' => 2500000,
//     'optimized_size' => 450000,
//     'saved_bytes' => 2050000,
//     'saved_percentage' => 82.0
// ]

echo "Saved: " . $optimizer->formatFileSize($comparison['saved_bytes']);
// Output: "Saved: 2.00 MB"

Helper Methods

$optimizer = ImageOptimizer::make();

// Get sanitized filename for storage
$filename = $optimizer->getOptimizedFilename($uploadedFile);
// "my_photo.webp"

// Get current format
$format = $optimizer->getFormat();
// "webp"

// Get temp file path
$path = $optimizer->getTempPath();

// Delete the temp file once you've stored it
$optimizer->cleanup();

Available Methods

Format Methods

Method Description
format(string $format) Set output format (webp, jpg, png, gif, avif)
toWebp() Convert to WebP format
toJpg() Convert to JPEG format
toPng() Convert to PNG format
toGif() Convert to GIF format
toAvif() Convert to AVIF format

Resize Methods

Method Description
maxWidth(int $width) Set maximum width (maintains aspect ratio)
maxHeight(int $height) Set maximum height (maintains aspect ratio)
maxDimensions(int $width, int $height) Set both max width and height

Quality & Settings

Method Description
quality(int $quality) Set quality 1-100 (affects jpg, webp, avif)
tempDir(string $path) Set custom temporary directory
withDefaults() Apply all defaults from config
maxInputPixels(?int $pixels) Reject inputs larger than this many pixels (default 40,000,000)
stripMetadata(bool $strip = true) Strip EXIF/GPS from jpg, webp, avif output (default on)
autoCleanup(bool $enabled = true) Delete the temp file when the instance is destroyed (default off)

format() only accepts webp, jpg, jpeg, png, gif, avif, bmp and throws InvalidArgumentException for anything else. Process methods throw InvalidArgumentException when the source is not a readable file or exceeds max_input_pixels.

Process Methods

Method Description
process(UploadedFile $file) Process uploaded file
processUploadedFile(UploadedFile $file) Alias for process()
processFromPath(string $path) Process from file path
processFromRequest(string $inputName) Process from request input name

Configuration

After publishing, you can customize these options in config/image-optimizer.php:

return [
    // Image driver: 'gd' or 'imagick'
    'driver' => env('IMAGE_OPTIMIZER_DRIVER', 'gd'),

    // Default output format
    'format' => env('IMAGE_OPTIMIZER_FORMAT', 'webp'),

    // Default quality (1-100)
    'quality' => env('IMAGE_OPTIMIZER_QUALITY', 85),

    // Default max dimensions (used with withDefaults())
    'max_width' => env('IMAGE_OPTIMIZER_MAX_WIDTH', 1200),
    'max_height' => env('IMAGE_OPTIMIZER_MAX_HEIGHT', 1200),

    // Temporary directory for processed files
    'temp_dir' => env('IMAGE_OPTIMIZER_TEMP_DIR', storage_path('app/temp')),

    // Reject images with more pixels than this (decompression bomb guard)
    'max_input_pixels' => env('IMAGE_OPTIMIZER_MAX_INPUT_PIXELS', 40000000),

    // Strip EXIF metadata (GPS, camera info) from jpg/webp/avif output
    'strip_metadata' => env('IMAGE_OPTIMIZER_STRIP_METADATA', true),
];

Security tip: keep temp_dir outside the public web root, and never pass user input straight into format() without your own validation.

Upgrading from 1.x to 2.0

  • Temp files are no longer deleted in the destructor. In 1.x, ImageOptimizer::make()->...->process($file) deleted the file as soon as the statement finished. Call cleanup() after storing the file, or opt in with autoCleanup().
  • format() (and the format config value) now throws InvalidArgumentException for unsupported formats instead of silently writing WebP with that extension.
  • Inputs larger than max_input_pixels and paths that aren't readable files now throw InvalidArgumentException.
  • EXIF metadata is stripped by default; use stripMetadata(false) to keep it.
  • Requires intervention/image ^3.6.

Integration Examples

With Spatie Media Library

use Christyoga123\ImageOptimizer\ImageOptimizer;

// Optimize before adding to media collection
$tempPath = ImageOptimizer::make()
    ->toWebp()
    ->maxDimensions(1200, 1200)
    ->quality(85)
    ->process($request->file('photo'));

$model->addMedia($tempPath)
    ->usingFileName('optimized-photo.webp')
    ->toMediaCollection('photos');

With Laravel Storage

$optimizer = ImageOptimizer::make()
    ->toWebp()
    ->maxWidth(800);

$tempPath = $optimizer->process($request->file('image'));
$filename = $optimizer->getOptimizedFilename($request->file('image'));

// Store to disk
$path = Storage::disk('public')->putFileAs('uploads', $tempPath, $filename);

return response()->json(['path' => $path]);

In Form Request

// app/Http/Requests/StorePhotoRequest.php
public function passedValidation()
{
    if ($this->hasFile('photo')) {
        $tempPath = ImageOptimizer::make()
            ->withDefaults()
            ->process($this->file('photo'));

        $this->merge([
            'optimized_photo_path' => $tempPath
        ]);
    }
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email christianuswibisono@gmail.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.