Imagecache Laravel Package

Getting Started

1. Check your Laravel version first. 3.2.0 is the release that moved the package to Laravel 11/12 and dropped the older, EOL branches. If you're still on Laravel 9/10, pin ^3.1 and plan the framework upgrade before taking this in — there's no compatibility shim here, it's a hard constraint change in composer.json.

2. composer require onigoetz/imagecache

3. Publish the config and read it end to end — this is the package. Everything (routes, templates, cache location, driver, quality) is defined there:

   php artisan vendor:publish --tag=config
   

4. Make sure the cache directory is writable and reachable by the web server. If you're serving generated files from storage/, you'll need php artisan storage:link and the usual permission checks.

5. Define at least one template in config/imagecache.php — a name plus a list of manipulation actions (resize, crop, fit, etc.).

6. First real use case: drop a generated URL into a Blade view:

   <img src="{{ Image::url('uploads/hero.jpg', 'medium') }}" alt="">
   

   Hit the page, confirm the file lands in the cache directory, then confirm the second request is served straight from disk without re-processing.

Where to look first when something's wrong: the published config (template names and source path roots), then the cache directory contents, then the route the package registered.

Implementation Patterns

Treat templates as design tokens, not one-offs. Define a small set (thumb, card, hero, plus a 2x variant) and reference them by name everywhere. Scattering inline dimensions means every layout change becomes a code change in a dozen views.

Responsive images via srcset. Generate one template per breakpoint and compose them in a Blade partial or component so the <picture>/srcset markup lives in exactly one place:

<img src="{{ Image::url($path, 'card') }}"
     srcset="{{ Image::url($path, 'card') }} 1x, {{ Image::url($path, 'card_2x') }} 2x"
     alt="{{ $alt }}">

Wrap the facade, don't call it directly from views. A tiny helper or Blade component that takes a model/path and returns the URL gives you one place to swap in a CDN host, add a version query string, or return a placeholder for missing files.

Pair templates with your upload pipeline. Resize-on-render is fine for a handful of sizes, but if you have a hard requirement that images exist before a page goes live, generate the common templates as a post-upload job and let the route serve them as a fallback. This is also how you avoid the first-visitor latency hit on cold cache.

Protect private images at the route level. For anything user-specific, apply middleware to the package route (or wrap it) so authorization is checked before the file is served. Don't rely on unguessable filenames.

Custom actions belong in a service provider. If your design needs something the built-in actions don't cover (specific watermark placement, brand-specific padding), register your own action rather than post-processing the cached file elsewhere — otherwise the cache and the post-processor drift apart.

Test with Storage::fake-style isolation where you can, and assert on the URL shape rather than binary image output. For visual regressions, spot-check the generated files in a staging environment instead of trying to assert pixel output in CI.

Gotchas and Tips

• Cache keys don't know your source changed. Overwriting hero.jpg in place leaves the old derivative sitting in the cache. Either version your filenames, clear the cache directory as part of deploy, or key the URL on a file hash. This is the single most common "why is my image wrong" bug with this class of package.
• The upgrade is the headline of this release. Laravel 11/12 only. If you're on an older framework, 3.1.x is your terminal branch — and since the release notes cite security advisories as the reason for dropping them, "stay on 3.1 forever" isn't a strategy.
• Verify the driver. GD and Imagick differ in supported formats and in how they handle transparency, EXIF orientation, and colour profiles. Confirm which one is active in the environment you're debugging on (local and production often disagree), and confirm the PHP extension is actually installed — a missing extension produces confusing failures deep in the manipulation layer.
• Path handling is the sharp edge. Restrict allowed source roots in config and never pass a raw request parameter straight into a path. If you're accepting user input, resolve and validate against the configured roots before it reaches the package.
• Route collisions. If you already own the URL prefix the package registers, either change the prefix in config or you'll get surprising 404s that look like missing files rather than routing conflicts. Check php artisan route:list early.
• 404 vs 500 is diagnostic. A 404 usually means the source path isn't resolvable under the configured roots or the template name is wrong. A 500 means the manipulation itself failed — driver, corrupt source, or unwritable cache directory. Check permissions and storage/logs before touching config.
• Quality and format settings are global per template. If you need dramatically different quality for thumbnails vs. hero images, that's two templates, not one template with a runtime override.
• Long template chains cost real CPU. A five-action pipeline runs on every uncached request. Keep templates short and let the cache do the work.
• Extension points worth knowing: the config file (templates, paths, cache settings, driver), the package route (middleware, URL generation), and custom registered actions. Almost every reasonable customisation lives in one of those three — reach for a fork last.
• This release also enabled test coverage in CI, which is a good signal for future upgrades but doesn't change your day-to-day. Treat 3.2.0 as a compatibility bump with no new end-user features to adopt.