A cookieless, cache-friendly image proxy in Laravel (inspired by Cloudflare)

April 4, 2025

When you're building a fast, modern web experience, every byte counts, especially when you're serving images. Services like Cloudflare's image resizing are great because they allow you to transform and serve images dynamically via URL parameters, offloading the work to edge servers and delivering optimized assets to every device.

If you can use Cloudflare's image service, I recommend it!

Steve and I are building a single, multi-tenant platform to host our various sites (Postgres, SQLite, Rails + SQLite, and Screencasting.) We're both developers and we're moving quickly, so it's just easier to throw most images in the repo and deploy them all. This means we can't easily use Cloudflare's image resizing service. We could probably do some fancy DNS to make it work, but the local development story falls apart pretty quickly.

So instead, we built something similar in Laravel with very little effort!

The goal

We wanted to build a system that:

  • Accepts image transformation instructions via the URL (just like Cloudflare)
  • Resizes and encodes images on-the-fly
  • Delivers optimized, cacheable images with long-lived headers
  • Strips cookies to keep Cloudflare caching happy
  • Plays nicely with Laravel's routing and controller layer

We need to be able to resize any image once, and then have Cloudflare cache it for ~30 days. The only transformations we've implemented so far are the ability to resize, change the format, and change the quality. We can add more in the future!

Adding a proxy route

In our repo, the images are stored in the /public/images directory, which means they can be accessed on the web like this: highperformancesqlite.com/images/aaron.jpg.

In most hosting setups, Nginx will first see if the file exists in the public directory and if it does, it will serve that file.

Because /public/images/aaron.jpg exists on disk, Nginx will serve the image at the URL: highperformancesqlite.com/images/aaron.jpg. This means that this particular request will never even make it to Laravel. If someone requests an image with no transformations, it will still be served by Nginx. This is what we want!

We're going to create a slightly new route for proxy images. Instead of /images/{path} we're going to use /images/{options}/{path}. Because Laravel is serving routes after Nginx has checked to see if a file is there, we're guaranteed to not interfere with the serving of static, untransformed images.

Let's start by adding the route:

use \App\Http\Controllers\ImageController;
 
Route::get('/images/{options}/{path}', [ImageController::class, 'show'])
    ->where('path', '.*')
    ->name('image.show');
Code highlighting powered by torchlight.dev (A service I created!)

Importantly, we've added a wildcard route parameter that matches path. This means that when we request /images/{options}/a/b/c.jpg, the $path variable will be set to a/b/c.jpg, which is exactly what we want.

In our controller, we can start by simply responding with the image:

namespace App\Http\Controllers;
 
use Illuminate\Http\Request;
use Illuminate\Support\Facades\File;
 
class ImageController extends Controller
{
    public function show(Request $request, $options, $path)
    {
        // Create the correct path on disk.
        $path = public_path("images/$path");
        abort_unless(File::exists($path), 404);
 
        return response(File::get($path), 200)
            ->header('Content-Type', File::mimeType($path));
    }
}

This is a start! So far we've only recreated the default behavior, but also made it much, much worse.

Let's keep going!

Adding transformations

To handle the transformations, we use the excellent Intervention Image package. It gives us a fluent API for resizing, cropping, converting formats, and tweaking quality. It has a few drivers you can choose from to power your resizing. We're using the Imagick one.

It has a very simple API, with most things using named arguments and allowing you to pass sparse arguments if needed.

$image->scaleDown(width: $width, height: $height);

Passing the options in the URL

The only interface we offer to this image resizing tool is the URL. We're going to exactly mirror the Cloudflare Image URL structure.

Interestingly, Cloudflare does not use querystring params to control the transformations, but rather it requires those parameters to be in the path itself.

Here is an example from their docs:

<img src="/cdn-cgi/image/width=80,quality=75/uploads/avatar1.jpg" />

Notice the width=80,quality=75 smack dab in the middle there. This confused me a bit at first, but I have to imagine it's more reliable to put the options in the path when it comes to caching. I know some caches can get wonky with querystring params.

Whatever the reason, the folks at Cloudflare are smarter than me, so we'll go with it!

Ours will look like this:

<img src="/images/width=80,quality=75/aaron.jpg" />

Parsing the options from the URL

Laravel will always give us the first path segment in the $options variable, and the rest of the path in the $path variable. We'll break apart the options and the path at the top of our controller action:

namespace App\Http\Controllers;
 
use Illuminate\Http\Request;
use Illuminate\Support\Facades\File;
 
class ImageController extends Controller
{
    public function show(Request $request, $options, $path)
    {
        $path = public_path("images/$path");
        abort_unless(File::exists($path), 404);
 
        $options = $this->parseOptions($options);
 
        // ... more
    }
 
    protected function parseOptions($options)
    {
        return collect(explode(',', $options))
            ->mapWithKeys(function ($opt) {
                try {
                    $parts = explode('=', $opt, 2);
                    return [$parts[0] => $parts[1]];
                } catch (Throwable $e) {
                    return [];
                }
            })
            ->toArray();
    }
 
}
Code highlighting powered by torchlight.dev (A service I created!)

Now we have all of our options as an associative array:

[
    "width" => 80,
    "quality" => 75
]

So it's just a Mere Matter of Programming to apply them all. You can decide which transformations you support, but I'll show you the ones we've implemented:

namespace App\Http\Controllers;
 
use Illuminate\Http\Request;
use Illuminate\Support\Facades\File;
 
class ImageController extends Controller
{
    public function show(Request $request, $options, $path)
    {
        $path = public_path("images/$path");
        abort_unless(File::exists($path), 404);
 
        $options = $this->parseOptions($options);
 
        $image = Image::read($path);
 
        if (Arr::hasAny($options, ['width', 'height'])) {
            $width = $options['width'] ?? null;
            $height = $options['height'] ?? null;
 
            $image->scaleDown(width: $width, height: $height);
        }
 
        $quality = (int) Arr::get($options, 'quality', 100);
        $format = Arr::get($options, 'format', File::extension($path));
 
        [$mime, $encoder] = match (strtolower($format)) {
            'png' => ['image/png', new PngEncoder],
            'gif' => ['image/gif', new GifEncoder],
            'webp' => ['image/webp', new WebpEncoder(quality: $quality)],
            default => ['image/jpeg', new JpegEncoder(quality: $quality)],
        };
 
        return response($image->encode($encoder), 200)
            ->header('Content-Type', $mime);
    }
 
    protected function parseOptions($options)  ...
    {
        return collect(explode(',', $options))
            ->mapWithKeys(function ($opt) {
                try {
                    $parts = explode('=', $opt, 2);
                    return [$parts[0] => $parts[1]];
                } catch (Throwable $e) {
                    return [];
                }
            })
            ->toArray();
    }  
 
}

That's it! You've now got an image transformer that you can use right inside your Laravel app.

Improving cacheability

As cool as this is, we do not want our webserver doing this work more than once. Ideally zero times, but once is our next best option.

We need to introduce some caching!

We're not going to use Laravel's cache, but rather set the appropriate headers so that browsers and CDNs will cache these responses. Cloudflare sits in front of our sites, so we want to take advantage of that!

The first thing we're going to do is set some headers to our image response:

return response($encoded, 200)
    ->header('Content-Type', $mime)
    ->header('Cache-Control', 'public, max-age=2592000, s-maxage=2592000, immutable');

We're setting a few cache headers here:

  • public
    • The response can be cached by any cache, even if it normally would be considered private
    • Without public, caches like Cloudflare or a browser might refuse to store the response.
    • You want this on static assets like images!
  • max-age=2592000
    • This tells the browser how long (in seconds) it can cache the response.
    • 2592000 seconds = 30 days. We could potentially go longer!
    • After this time, the browser will consider the response stale and try to revalidate or fetch it again.
  • s-maxage=2592000
    • This is similar to max-age, but it’s specifically for shared caches like Cloudflare, Fastly, or other CDN edge nodes.
    • It overrides max-age for shared caches only, giving you finer control.
    • We likely don't need it in this particular case
  • immutable
    • This tells the browser: "Don’t bother checking back to see if this has changed."
    • Even if the user reloads the page or re-navigates to the URL, the browser will use the cached version without asking the server.
    • It’s perfect for versioned or unique URLs (like /img/width=300/aaron.jpg), where the URL changes if the content changes.

This is a good start, but we're not quite there yet! There's one more thing we need to modify in Laravel to make this response more cacheable.

Removing cookies from the response

One of the biggest gotchas with Cloudflare is that if your response includes cookies, it won't cache. So even if you set Cache-Control: public, you' still get cf-cache-status: BYPASS on subsequent requests.

To avoid this, we can create a middleware that removes the Set-Cookie headers, but only on image transformation routes:

use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;
 
class StripImageTransformCookies
{
    public function handle(Request $request, Closure $next): Response
    {
        // Let the request run all the way through the pipeline.
        $response = $next($request);
 
        // Only apply to our transform route.
        if ($request->routeIs('image.show')) {
            // Strip cookies
            $response->headers->remove('Set-Cookie');
        }
 
        return $response;
    }
}

You'll need to add this as the first (or one of the first) middlewares in your application.

In your bootstrap/app.php:

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;
 
return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(/* ... */)
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->web(
            append: [
                \App\Http\Middleware\HandleInertiaRequests::class,
                \Illuminate\Http\Middleware\AddLinkHeadersForPreloadedAssets::class,
            ],
            prepend: [
                \App\Http\Middleware\StripImageTransformCookies::class, 
            ]
        );
    })
    ->create();

Our middleware is now registered and only applies to that one specific route. This keeps the rest of the app functioning normally while letting Cloudflare happily cache our images.

Note that you cannot just add this as a middleware on the route. Because we need this to run after the Laravel middlewares that add the cookies, it must be registered as one of the first middlewares in the web group.

When you load the /images/width=80/aaron.jpg path in your browser the first time, Laravel will handle resizing the image and returning it to the browser. The second time you load it, you should see a cf-cache-status: HIT header on the response, which means it never had to go to your server at all!

Rate-limiting

A user on Reddit made a good comment (amazing, right!) about adding rate-limiting. We don't want someone to write a for loop and just hammer our server with transformation requests. We can use Laravel's built-in RateLimiter to help us here.

class ImageController extends Controller
{
    public function show(Request $request, $options, $path)
    {
        if (App::isProduction()) { 
            $this->ratelimit($request, $path);
        }
 
        // more...
    }
 
    protected function ratelimit(Request $request, $path): void
    {
        $allowed = RateLimiter::attempt(
            key: 'img:' . $request->ip() . ':' . $path,
            maxAttempts: 2,
            callback: fn() => true
        );
 
        if (!$allowed) {
            throw new HttpResponseException(Redirect::to("/images/$path"));
        }
    }
}

To construct the cache key, we use the user's IP and the path of the image they are trying to load. Importantly, we exclude the options from our cache key. (Be sure to configure your trusted proxies in Laravel so that you're getting the user's IP and not Cloudflare's IP.)

If we're running in production, you can only transform a given path twice per minute. This may sound shockingly low, but remember our setup!

After the first transformation request, the image will cached on Cloudflare. The vast majority of users will never request an image that needs to involve our server. Most requests will be served from Cloudflare's cache directly.

One unlucky user will have to populate the cache though! On the off chance we're using the same image transformed differently in two places, that's allowed.

For example, here are two requests that will resolve to the same cache key:

<img src="/images/width=100,quality=75/aaron.jpg" />
<img src="/images/width=300,quality=95/aaron.jpg" />

This seems unlikely, but possible! In this scenario, both would transform and load. But if a third request comes in for a transformed aaron.jpg then we're simply going to redirect them to the full, unmodified image. Even in the failure case, they still get an image (also served from Cloudflare, most likely!)

This image transformer lets us serve optimized images, cut payload sizes, and leverage browser/CDN caching all while keeping Laravel at the heart of our app.

It's simple, powerful, and surprisingly fun to build.

Let me know what you think!

Me

Thanks for reading! My name is Aaron and I write, make videos , and generally try really hard .

If you ever have any questions or want to chat, I'm always on Twitter.

If you want to give me money (please do), you can buy my course on SQLite at HighPerformanceSQLite.com or my course on screencasting at Screencasting.com . On the off chance you're a sophomore at Texas A&M University, you can buy my accounting course at acct229.com .

You can find me on YouTube on my personal channel . If you love podcasts, I got you covered. You can listen to me on Mostly Technical .