christyoga123/image-optimizer
| Install | |
|---|---|
composer require christyoga123/image-optimizer |
|
| Latest Version: | v2.0.0 |
| PHP: | ^8.1 |
| Laravel: | 10 – 13 |
| License: | MIT |
| Last Updated: | Nov 4, 2026 |
| Links: | GitHub · Packagist |
Laravel Image Optimizer
A fluent Laravel package for optimizing images - resize, convert formats (WebP, JPG, PNG, AVIF), and reduce file size while maintaining quality.
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_diroutside the public web root, and never pass user input straight intoformat()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. Callcleanup()after storing the file, or opt in withautoCleanup(). format()(and theformatconfig value) now throwsInvalidArgumentExceptionfor unsupported formats instead of silently writing WebP with that extension.- Inputs larger than
max_input_pixelsand paths that aren't readable files now throwInvalidArgumentException. - 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.
Related Packages
Laravel file & image upload service with multi-format processing (resize, conver...
Dynamically resize an image and returns the URL using Intervention and Storage
Version History
| Version | Released | PHP | Laravel | License |
|---|---|---|---|---|
| v2.0.0 | ^8.1 | ^10.0| | MIT | |
| v1.1.0 | ^8.1 | ^10.0| | MIT | |
| v1.0.0 | ^8.1 | ^10.0| | MIT |