Image Service Laravel Laravel Package

Getting Started

Version 2.0.0 is a major release — treat this as a migration, not an upgrade. Before touching application code:

1. Read the full changelog diff (1.1.0...2.0.0) and any UPGRADE.md in the tag. The release note itself carries no detail, so the compare view is your only source of truth for renamed namespaces, changed method signatures, and dropped config keys.
2. Pin the constraint explicitly ("ringier-imu/image-service-laravel": "^2.0") in a branch, run composer update ringier-imu/image-service-laravel, and check composer why-not if it refuses to move.
3. Re-publish the config: php artisan vendor:publish --tag=image-service-config --force into a scratch path, then diff against your existing config/image-service.php. Major versions of this package have historically reshaped config keys and defaults; a stale published config is the most common cause of a "working" install that silently produces wrong URLs.
4. Confirm the service provider and facade alias still resolve. If 2.0 moved to package discovery or renamed the facade accessor, config/app.php aliases from 1.x will fatal at boot.

First use case: instantiate the service through the container (not the facade) in a tinker session or a throwaway route, point it at a test image, and confirm you get a URL back with your configured host and credentials. Validate that before migrating a single Blade template — it isolates credential/config problems from API-shape problems.

Implementation Patterns

Wrap the package behind a thin application-level adapter. Call it App\Support\ImageUrl or a MediaPresenter. Every controller, Blade view, API resource, and Nova/ Filament field then calls your adapter rather than the package. When 2.x renamed methods — or when 3.x does — you patch one class instead of grepping 200 templates. This is the single highest-leverage pattern with an image-service wrapper, because URL construction leaks into views by nature.

Keep transformation presets in config, not in views. Define named presets (thumb, hero, og) in your own config file mapping to package transformation calls. Views ask for a preset name; the preset definition is the only place that knows the package's fluent API. This also makes it trivial to A/B a new crop strategy or swap fit for fill without touching templates.

Store only the image identifier, never the URL. Persist the service-side ID/reference on your model and resolve the URL at render time. Cached absolute URLs rot when the host, signing key, or transformation defaults change — which is exactly what a major version bump does. If a migration in 2.0 changed how URLs are signed or how the host is composed, stored URLs in your DB, sitemap, and email templates are now dead links.

Cache URL generation, not the image. URL building is cheap but not free inside a loop over 50 products × 4 srcset widths. Cache the generated string keyed on (image id, preset, package version). Including the package version in the cache key means a 2.x deploy invalidates stale URLs automatically instead of serving malformed requests to the image host.

Queue anything that hits the API. Uploads and deletes are network calls. Do them in a job with retries and a backoff; do URL generation inline. Mixing the two is how you get 30-second page loads when the image service has a bad minute.

Testing pattern: bind a fake implementation of your adapter in the test container so feature tests never reach the image service, then keep a small tagged integration suite (@group image-service) that exercises the real client against a staging credential set. This is where you'll catch 2.0's breaking changes in CI rather than production.

For a 2.0 rollout specifically: ship it behind a config flag or feature toggle, deploy to staging with production-shaped data, and diff rendered HTML for a sample of pages. Image URLs are visually obvious when wrong and easy to eyeball in a diff — cheaper than reading a changelog.

Gotchas and Tips

• The empty release note is the trap. A changelog that is only a compare link means the maintainers considered the commit history sufficient documentation. Budget time to read the actual diff, especially src/ and config/. Look for removed @deprecated methods — those are your 1.x call sites.
• Config caching bites on upgrade. php artisan config:cache will happily serve a cached 1.x config shape after you upgrade. Always config:clear/config:cache in the deploy script and in local dev after pulling the tag.
• Check for a renamed or removed facade. If code calls the facade statically in a service provider's register() or in a config file, a missing alias produces confusing class-not-found errors far from the cause.
• Credential/env var renames. Major versions of API clients frequently rename env keys (IMAGE_SERVICE_*). A missing key often degrades silently to an unsigned or public URL rather than throwing — so assert on the generated URL in a test.
• Signing and TTL. If 2.0 changed URL signing or introduced expiry, anything long-lived (sitemaps, RSS, transactional email, queued notifications) will serve expired links. Grep for stored URLs and scheduled jobs that pre-generate them.
• Semver honesty check. A 0.x → 1.x style jump or a 1.x → 2.0 on a small package doesn't guarantee a painful migration; equally, "2.0" sometimes only means a PHP/Illuminate minimum bump. Read the composer.json diff first — version constraints there tell you immediately whether your Laravel version is even supported.
• Extension points: favour the container binding and any published interface over subclassing concrete classes. If the package exposes a contract for the HTTP client or URL builder, bind your own; that survives major versions far better than overriding internals.
• Rollback plan. Because this is a major version, keep the old constraint in composer.json on the release branch so a git revert of the lock file restores a known-good state without hunting for the previous tag.