Design Customization Bundle Laravel Package

Getting Started

This release (v0.3.3) is a small, additive change: a new getCustomImageAbsoluteUrl helper. Nothing is removed or renamed, so existing installs upgrade with a plain composer update — no migration or config republish required.

First contact points, in order:

1. The class exposing the new method. Grep the vendor directory for the method name to find which trait/model/helper it lives on — that tells you whether it is a model concern (likely, given the get...Url naming convention common to Eloquent accessors) or a standalone service.
2. The package's config file, if one is published (config/*.php in the package). Look for a disk name, a base path, or a fallback/placeholder URL setting — the "custom" in getCustomImageAbsoluteUrl strongly implies a user-supplied or overridden image distinct from some default image.
3. Existing tests inside the package. For a one-method release, the test file is the fastest and most accurate specification of behaviour: what it returns when no custom image is set, whether it prefixes a disk URL or APP_URL, and whether it returns null or a placeholder.

First use case to validate in a scratch route or tinker session:

$model = SomeModel::first();

// Confirm it returns an absolute URL, not a relative path
dump($model->getCustomImageAbsoluteUrl());

// Confirm the no-custom-image path behaves predictably
$blank = SomeModel::factory()->create(['custom_image' => null]);
dump($blank->getCustomImageAbsoluteUrl()); // null? default? placeholder?

Once you know the null/fallback behaviour, you can use it safely in Blade (<img src="{{ $model->getCustomImageAbsoluteUrl() ?? asset('img/placeholder.png') }}">) and in API resources.

Implementation Patterns

Blade presentation. The obvious win is replacing hand-rolled Storage::disk(...)->url(...) chains with a single call. Wrap it once in a view component or accessor so that fallback logic lives in exactly one place rather than being repeated in every template:

<img src="{{ $user->getCustomImageAbsoluteUrl() ?? asset('img/avatar-default.png') }}" alt="{{ $user->name }}">

API resources. Because the method returns an absolute URL, it is directly serialisable — no client-side URL joining, no asset() calls leaking into your API layer. Keep it out of toArray() on the model, and expose it explicitly in the resource so the contract is visible:

public function toArray($request): array
{
    return [
        'id'         => $this->id,
        'name'       => $this->name,
        'avatar_url' => $this->getCustomImageAbsoluteUrl(),
    ];
}

Caching and invalidation. If the URL is generated from a stored path plus a disk config, it is cheap to recompute — prefer calling it fresh over persisting the result in a database column. If you do cache it (e.g. in a Redis payload for a heavy index endpoint), invalidate whenever the underlying image attribute or disk config changes.

Environment parity. Absolute URLs are environment-sensitive by nature. Adopt the habit of asserting the value in at least one feature test per environment-critical screen, so a misconfigured APP_URL or disk url key fails in CI rather than in production emails and OG tags.

Queue/mail contexts. This is where absolute URLs actually earn their name — emails, PDFs, and notifications rendered outside a request context have no relative-URL base. Use this helper rather than Storage::url() in those paths.

Gotchas and Tips

• Absolute does not mean correct. The method can only prefix with what it knows: a disk's url config or APP_URL. Behind a proxy or on a multi-domain app, verify TrustProxies and APP_URL before blaming the package. Symptom: http://localhost/... appearing in staging emails.
• Null vs. placeholder is the critical unknown. Confirm the no-custom-image branch before shipping. If it returns null, every call site needs a ?? fallback; if it returns a configured placeholder, do not double up with your own default. Pick one convention project-wide and document it in your team notes.
• Cache-busting may be absent. A method that only builds a URL will not append a version or mtime query string. If users replace custom images and see stale ones through a CDN, add your own ?v= suffix at the call site rather than assuming the package handles it.
• N+1 risk in listings. If the method touches a related model or a filesystem call per invocation, rendering it in a loop of 50 records can hurt. Check the implementation; if it resolves a relation, eager-load it (->with('customImage')).
• Prefer the accessor over new code paths. Resist writing your own getImageUrlAttribute alongside it — two sources of truth for image URLs is exactly the drift this helper should prevent. Deprecate your local version and route everything through the package method.
• Upgrade cheaply, but pin. v0.3.x is pre-1.0, so minor bumps can still carry signature changes. Keep a ^0.3 constraint, run the package's own test suite (or your integration tests) after each bump, and check the changelog for behaviour changes to the fallback path in particular — that is the piece most likely to shift silently.
• Extension point. If the URL shape does not suit you (custom CDN domain, signed URLs), the clean move is a small wrapper on your own model or a dedicated presenter that calls the package method and post-processes it, rather than subclassing or editing vendor code.