Laravel Cloud Images Laravel Package

Getting Started

v4.4.0 is a compatibility-only release: it adds Laravel 13 and PHP 8.5 support on top of v4.3.2. There are no API changes, no deprecations, and no config changes, so this is a safe composer update makeabledk/laravel-cloud-images for existing installs. The only reason to plan work is if you were previously pinned to Laravel 12 / PHP 8.3–8.4 — you can now widen those constraints, but you should re-run your image test suite after the framework bump rather than after the package bump, since Laravel major upgrades are the actual risk here.

First steps for a new install:

1. composer require makeabledk/laravel-cloud-images
2. Publish the config (php artisan vendor:publish --tag=cloud-images or the tag listed in the README) and read config/cloud-images.php top to bottom before writing any code — the provider/base-URL setup and the default transformation presets live there, and nearly every "why is my URL wrong" question is answered by that file.
3. Set the base/cloud URL (and credentials if your provider uses signed URLs) via .env, never inline in config, so staging and production can point at different buckets/containers.
4. Generate one URL in a route or tinker session and eyeball it against what your CDN/provider expects before wiring it into Blade.

The first real use case to implement is almost always the same: replace hardcoded <img src="/images/hero.jpg"> in a Blade layout with a generated, transformed URL plus a srcset, then verify caching headers and the fallback path for missing images.

Implementation Patterns

Config-driven presets, not inline transformations. Define named presets (thumbnail, hero, card, og-image) in the config and reference them by name from application code. This gives you one place to change compression/format/resize policy globally, and it makes the transformation arguments greppable when a designer asks "what size is the card image?".

A thin application-level wrapper. Don't sprinkle the package's API across controllers and Blade templates. Add a small service (e.g. App\Support\ImageUrl or a Blade component <x-image>) that takes a model/path plus a preset name and returns the URL and srcset. When you later need to swap providers or add signed URLs for private assets, you change one class instead of 60 templates. This is also where you centralise the "asset missing" fallback.

Model accessors for image sets. For models with several image fields, expose an accessor or a small value object ($post->image('hero')) rather than calling the package directly from views. It keeps controllers thin and makes it trivial to add placeholder/lqip behaviour later.

Responsive images as the default path. Any user-facing <img> should go through a srcset helper with 2–4 width breakpoints tied to your CSS layout, plus explicit width/height to avoid CLS. Reserve single-URL generation for OG/meta tags, emails, and PDFs where srcset is meaningless.

Environment separation. Point local/dev at a passthrough or local-disk driver and staging/production at the real cloud provider, using .env values in the config. Nothing is worse than local development burning CDN transformations or, conversely, production silently falling back to origin files because an env var was missing.

Cache-busting on content change. If your provider keys on the path, a replaced image at the same path will serve stale CDN content. Either version the path with a hash/updated_at column or use the package's versioning hook if present. Bake this into the wrapper so it's automatic.

Pre-warm on upload. For user-uploaded images, trigger the first transformation immediately after upload (a synchronous HEAD/GET) so the first visitor doesn't eat the generation latency.

Gotchas and Tips

• This release is a version-constraint unlock, not a feature. Treat v4.4.0 as "we can now upgrade Laravel/PHP"; the meaningful testing surface is your framework upgrade, not the package diff. Locking to ^4.4 is fine, but don't expect behavioural changes.
• Check composer why-not before widening constraints. If another dependency blocks Laravel 13 or PHP 8.5, the package bump alone won't get you there, and you'll get a confusing resolution error that looks like it's the image package's fault.
• Config cache is the usual culprit. After editing config/cloud-images.php, run php artisan config:clear. In production, config:cache during deploy — editing the file on the server without re-caching silently keeps the old presets.
• Double-encoding in query strings. If you build transformations by hand and pass them through url()/e() in Blade, ampersands and commas get escaped and the provider quietly ignores the malformed parameters. Always output with {!! !!} for the fully-built URL, or better, let the package build it and only escape the attribute quoting.
• Provider-specific signing. If you use signed URLs, remember they expire — don't persist them in the database or cache them past their TTL. Cache the path and sign at render time.
• Disk vs. CDN path mismatch. A URL that 404s usually means the storage disk prefix and the config's base path disagree (e.g. public/ included in one but not the other). Verify by comparing a generated URL to a known-good file path in your bucket.
• Tests should assert URLs, not bytes. Snapshot the generated URL structure in a feature test so a config refactor doesn't silently change every image size in production. Avoid hitting the real CDN in CI; use a fake/passthrough driver.
• Extension point: if you need provider behaviour the package doesn't cover, prefer wrapping it in your own service over forking — the wrapper survives package majors, a fork doesn't. Keep the wrapper's public methods narrow (one method per preset use case) so future upgrades of this package, including the eventual Laravel 14/PHP 8.6 bump, stay a one-line composer change.