Weave Code
Image Optimizer Laravel Package
spatie/image-optimizer
Optimize PNG, JPG, WEBP, AVIF, SVG and GIF images in PHP by running them through a chain of tools like JpegOptim, Optipng, Pngquant and SVGO. It auto-detects installed binaries and overwrites files in place with smaller versions.
spatie/image-optimizer is a PHP package that shrinks PNG, JPG, WEBP, AVIF, SVG and GIF files by running them through a chain of native image optimization tools. It automatically detects which binaries are installed on your system and applies them, so a single optimize($path) call overwrites your image with a smaller, optimized version.
use Spatie\ImageOptimizer\OptimizerChainFactory;
OptimizerChainFactory::create()->optimize($pathToImage);
- Auto-detection of available optimizers (JpegOptim, Optipng, Pngquant, SVGO, Gifsicle, Cwebp…)
- One-line API via
OptimizerChainFactory - Custom chains — pick your own tools and options
- Framework integrations for Laravel, WordPress and SilverStripe
- Battle-tested with 2,800+ GitHub stars
Frequently asked questions about Image Optimizer
- How do I install spatie/image-optimizer in a Laravel app?
- Run composer require spatie/image-optimizer, then create the chain with OptimizerChainFactory::create() and call optimize($path). For Laravel config-driven setup, install spatie/laravel-image-optimizer and publish its config instead of instantiating the factory at call sites. The core package itself has no Laravel service provider.
- Which Laravel and PHP versions does spatie/image-optimizer support?
- The package is a framework-agnostic Composer library that works with PHP 8.1+; the Laravel integration is used with Laravel 10 through 12. Because the core library has no framework coupling, Laravel version constraints come from spatie/laravel-image-optimizer, not the optimizer itself.
- Do I need jpegoptim, pngquant, and other binaries installed?
- Yes. The package is an adapter over OS-level CLI tools, so it only optimizes formats whose binaries are present: jpegoptim, optipng, pngquant and gifsicle from apt, webp tools, libavif-bin 0.9.3+ for AVIF, and SVGO via npm for SVG. It auto-detects installed binaries and silently skips missing ones, so provision your runtime image deliberately and verify on Alpine or arm64 if you use them.
- Does spatie/image-optimizer work with Laravel filesystem disks like S3?
- Not directly; it only understands local filesystem paths. For object storage, download the asset to a local temp path, run the optimizer chain, then re-upload the optimized file. Pair this with your own data model if you need to track which assets have already been optimized.
- Does spatie/image-optimizer overwrite the original image?
- Yes, the default optimize($path) call overwrites the source file in place, which means a bug, timeout, or interrupted process can leave a truncated asset. Pass an explicit output path or operate on a copy so the original remains intact. Also note the package is not idempotent: re-running it on already optimized files can re-encode lossily and degrade quality, so track optimized assets yourself.
- What image formats can spatie/image-optimizer optimize?
- It supports PNG, JPG, WEBP, AVIF, SVG and GIF, each through its corresponding CLI tool. If a tool for a format is absent, that format is simply skipped rather than failing loudly. SVG support depends on Node and SVGO being available in the runtime image.
- Is spatie/image-optimizer safe for SVG files?
- The maintainers explicitly warn that SVGO can break SVGs, even though risky plugins like cleanupIDs and removeViewBox are excluded by default. That is not a complete guarantee, so treat SVG optimization as best-effort and validate output before serving it. If SVG safety is a hard requirement, consider handling SVG out-of-band rather than in the upload path.
- What happens if an optimization binary is missing?
- The package detects which binaries are installed and silently skips the rest, so a partially provisioned container degrades quietly instead of throwing. A missing binary is indistinguishable from a no-op optimization unless you wire and inspect a PSR-3 logger. Decide your fallback explicitly: ship the original or fail the upload, and monitor for it.
- Is spatie/image-optimizer lossy and does it strip EXIF metadata?
- Yes, the defaults are lossy: jpegoptim uses -m85, pngquant is lossy, and cwebp uses -q90. JPEG optimization also uses --strip-all, which removes EXIF data including orientation and copyright, so verify EXIF-rotated uploads and any contractual metadata requirements. Lossy settings are product decisions per asset class, so sign off on them rather than accepting defaults blindly.
- Does spatie/image-optimizer resize images?
- No. It is a byte-shrinker that runs after a resize step, so pair it with spatie/image, Intervention Image, or your own resizing pipeline. Without resizing first you can still ship a 4000px image that is merely optimized. Also pin binary versions like SVGO and pngquant in your base image, because current releases differ from the README's SVGO 1 and pngquant 2 targets.
Weaver
How can I help you explore Laravel packages today?