league/glide
Glide is an easy on-demand image manipulation library for PHP with a simple HTTP API. It resizes, adjusts, and applies effects, caches images with far-future headers, supports GD, Imagick, and libvips, and works with Flysystem and PSR-7/HttpFoundation responses.
composer require league/glide
You also need an image driver. GD is the default and is usually already compiled in; Imagick (ext-imagick) and libvips (ext-vips) give better quality/performance and are wired via the driver option. Check php -m and php -i | grep -i gd before anything else — most "it outputs a blank/garbled image" reports start here.
Glide's whole surface is one factory call plus one HTTP entry point:
use League\Glide\ServerFactory;
use League\Glide\Responses\SymfonyResponseFactory;
$server = ServerFactory::create([
'source' => storage_path('app/public/images'),
'cache' => storage_path('app/public/images/cache'),
'driver' => 'gd', // gd | imagick | vips
'response' => new SymfonyResponseFactory(request()),
'defaults' => ['q' => 80, 'fm' => 'pjpg'],
]);
Your first use case is almost always a catch-all route that maps query-string parameters onto League\Glide\Server:
Route::get('img/{path}', function (League\Glide\Server $server, Illuminate\Http\Request $request, string $path) {
return $server->getImageResponse($path, $request->query());
})->where('path', '.*');
GET /img/products/chair.jpg?w=800&h=600&fit=crop now yields a resized, cached, far-future-expiry image. Illuminate\Http\Response extends Symfony's, so SymfonyResponseFactory slots straight into Laravel's return pipeline.
Where to look first:
docs/api/ in the repo (mirrored at glide.thephpleague.com) — the parameter reference is the thing you'll consult daily: w, h, fit, crop, fm, q, dpr, bri, con, blur, mark*, or, strip.League\Glide\Server — getImageResponse(), outputImage(), makeImage(), deleteCache(), clearCache(), getSource(), getCache().ServerFactory's $config array — every behavioural switch (source_path_prefix, cache_path_prefix, base_url, group_cache_in_folders, cache_with_file_extensions, max_image_size) lives there.Bind the server once as a singleton. Building a Server per request is wasteful and makes cache config drift-prone. Put the config array in config/glide.php and register a singleton in a service provider; inject League\Glide\Server into controllers, jobs and commands.
Build URLs, never hand-concatenate them. Use the URL builder so parameters are consistent and signatures are correct:
use League\Glide\Urls\UrlBuilderFactory;
$urls = UrlBuilderFactory::create('/img/', config('glide.signature_key'));
// Blade: <img src="{{ $urls->getUrl('products/chair.jpg', ['w' => 800, 'fit' => 'crop']) }}">
base_url here must exactly match the route prefix, including the trailing slash. A mismatch silently produces 404s instead of images.
Sign URLs when the cache is public-facing. Without signatures anyone can request ?w=1 through ?w=9999 and flood your cache. Enable a signing key, then verify inbound requests before handing off to Glide:
use League\Glide\Signatures\SignatureFactory;
use League\Glide\Signatures\SignatureException;
try {
SignatureFactory::create(config('glide.signature_key'))
->validateRequest($path, $request->query());
} catch (SignatureException $e) {
abort(403);
}
This pairs naturally with middleware so your route closure stays trivial.
Pre-generate on upload, invalidate on replace. First-request generation is fine for long-tail assets, but product galleries and hero images benefit from warming the cache in a queued job:
$server->makeImage('products/chair.jpg', ['w' => 800, 'h' => 600, 'fit' => 'crop']);
On replace or delete, call $server->deleteCache($path) — it drops every variant for that source path (use clearCache() only for admin "nuke everything" actions). Forgetting this is the #1 source of "the client says the old logo is still showing" tickets.
Decouple source and cache. source and cache accept anything Flysystem accepts, so the common production layout is source on S3 (League\Flysystem\AwsS3V3\AwsS3V3Adapter) with cache on a local fast disk, or both on S3 behind a CDN. In that case pass Flysystem Filesystem instances instead of paths.
Allowlist parameters at the edge. Glide happily accepts anything in the documented API; that's not the same as wanting ?blur=100&bri=-100 available to the public. Normalise query strings in middleware (clamp w/h, drop unknown keys) so cache cardinality and abuse surface stay bounded.
Test with an in-memory adapter. League\Flysystem\InMemory\InMemoryFilesystemAdapter for both source and cache lets you assert on makeImage() output dimensions without touching disk — much faster than fixture directories.
defaults, quality, or the driver does not regenerate existing files. Roll out a config change and you must clear the affected cache or bump cache_path_prefix to force a cold start.cache_with_file_extensions derives cache filenames from the source extension. Historical .pjpg weirdness lives here; if progressive JPEGs land with odd extensions, check this flag before filing a bug.or=auto fixes rotated phone photos, and 4.1 added a strip parameter controlling whether EXIF metadata is kept. Stripping also drops colour profiles and copyright fields — a legal consideration for editorial imagery. 4.2 additionally shrinks large JPEGs on load when resizing; that reduces memory pressure but doesn't remove it.policy.xml (memory, width, height, map) will refuse large sources with an unhelpful exception, and GD dies with a PHP fatal on memory_limit. Raise memory_limit for the image route/queue worker and test with your largest realistic upload.fm=webp, avif (added 2.1), tiff (2.2.2) and JPEG XL (4.2) all require the extension to actually be compiled in. Since 4.0, an invalid fm throws rather than silently degrading — good, but wrap the route so users see a 400/404 rather than a stack trace.fill vs fill-max. fill upscales small images to hit the exact box; fill-max (2.2+) never upscales. For responsive grids, fill-max is usually what you meant.crop=50,35) with fit=crop. A 1px background line artefact on these was fixed in 4.1 — worth upgrading if you see hairlines.markalpha is 0–1, normalised during the 4.0 Intervention Image migration. If you carried an old 0–100 value over, watermarks will be invisible.source_path_prefix scoped so Glide's path validator can't be walked out of; never build the source root from user input.Cache-Control, so a CDN will pin a stale variant even after deleteCache(). Purge by URL pattern, or version your image paths on upload.How can I help you explore Laravel packages today?