Useful Bundle Laravel Package

Getting Started

The v3 release note names a single unit of work — AttachAndResizeModelTrait — so treat v3 as a trait-centric major release rather than a broad feature drop. Start by locating that trait and reading it end to end before touching the README; with a terse changelog, the trait source and its type hints are the most reliable contract you have.

Minimal steps:

1. composer require <vendor>/<package>^3.0 and confirm the service provider is auto-discovered (php artisan package:discover). If the package ships a config file, publish it (vendor:publish --tag=...) and diff it against the previous major's config — v3 majors routinely rename or restructure config keys.
2. Open src/.../AttachAndResizeModelTrait.php. Note three things precisely: the expected attribute/column names it reads and writes, the disk it defaults to, and whether it hooks into boot<TraitName>() model events (likely saved/deleted for cleanup).
3. Add use AttachAndResizeModelTrait; to one small model, add the columns it expects (or point it at existing ones via the documented properties), and attach a single file in php artisan tinker using Storage::fake('public') guarded by a test rather than a real upload.
4. Verify: original stored, derivative(s) generated at the expected dimensions, path persisted on the model, and the resize recorded correctly under the configured disk.

First use case to prove out: a User with an avatar column, one upload, one resize preset, then $user->delete() to confirm the files and derivatives are cleaned up. That single loop exercises attachment, resizing, persistence, and cleanup — the four things this trait most plausibly owns.

Implementation Patterns

Trait-on-model, config-in-config. Keep every resize dimension in the published config (or in model-level overrides if the trait exposes them) rather than hardcoding numbers in controllers. Presets named by intent (avatar, thumbnail, hero) age far better than 300x300, and they let you resize once for many consumers when you add a new surface later.

Explicit attach methods over magic properties. Wrap the trait's attach call in a small service or form-request-driven action:

final class AttachAvatar
{
    public function __invoke(User $user, UploadedFile $file): void
    {
        $user->attachAndResize($file, preset: 'avatar'); // confirm method name from the trait in v3
        $user->save();
    }
}

This keeps controllers thin and gives you one place to swap in queued processing later without touching call sites.

Queue the work if the trait allows it. Image resizing is CPU- and memory-bound; doing it in the request cycle is fine for one small avatar and painful for a bulk import. If v3 exposes a queued path (or a ShouldQueue companion job), prefer it for anything user-facing at volume, and make sure the job is idempotent since retries will re-run the resize.

Decouple the derivative from the source. Store the original untouched and generate derivatives into a predictable, convention-based path (avatars/{id}/{preset}.jpg). That convention lets you regenerate derivatives later with an artisan command instead of guessing filenames, and it makes CDN/cache invalidation tractable.

Integrate with existing media handling deliberately. If the project already uses Spatie Media Library, intervention/image, or a CDN-backed disk, decide early whether this trait is the single attachment layer or a supplement. Two systems writing to the same column is the most common source of "why did my image revert" bugs.

Test against a fake disk. Every test that touches the trait should begin with Storage::fake($disk) and end with Storage::disk($disk)->assertExists(...). This keeps CI fast and catches the path-convention regressions that image packages are prone to between majors.

Gotchas and Tips

The v3 changelog is a one-liner, which is itself the biggest risk. There is no documented migration path, no deprecation list, and no diff of config keys. Assume breaking changes: renamed config keys, changed default disk, altered method signatures, or a different column-naming convention. Before deploying, diff the published config against your old one and grep your codebase for every call into the trait — a major version that only says "Trait (v3)" is signalling an API reshuffle you have to discover yourself.

Verify the column contract explicitly. Traits that "attach" usually infer column names from the model. Check whether v3 requires declared properties (e.g. $attachmentAttribute, $resizePresets) and whether it silently no-ops when they're missing. A silent no-op — file saved, column left null — is the classic failure mode and won't throw.

Image driver and memory. If resizing uses GD or Imagick, confirm both PHP extensions and their versions on every environment, including CI and Horizon workers. GD's memory ceiling bites on large uploads well before PHP's memory_limit warning appears; if the trait offers a driver config, pin it rather than relying on what's installed.

EXIF orientation. Portrait phone photos routinely come out sideways unless the pipeline calls orientate()/autoOrient(). Check whether the trait does this for you in v3 — if it doesn't, orientate before resizing, or your avatars will be rotated on mobile-originated uploads only.

Cleanup on update and delete. Confirm v3 removes the old derivative when a model is updated with a new file, not just on deleted. Orphaned files are invisible until a storage bill or an audit turns them up. Add a scheduled prune command as a backstop.

Storage quirks on non-local disks. S3 and other object stores don't have directories and are slow at exists(); if the trait probes for files before writing, you'll pay latency per request. Also check that derivative writes go through the disk adapter rather than file_put_contents to a path — that breaks on remote disks after a config-only change.

Debugging checklist when an image doesn't appear: (1) Storage::disk($d)->exists($path) from tinker, (2) the persisted column value, (3) file permissions/umask on storage/app, (4) the APP_URL used to build the public URL, (5) whether the queue worker was restarted after the deploy that introduced v3. That order resolves the large majority of "resize silently failed" reports.

Extension points to look for in v3. Whether the trait fires model events, exposes a resizing/resized hook, or accepts a custom filename callback determines how much you can extend it without a fork. If those seams exist, prefer them over subclassing the trait's behaviour — traits composed onto Eloquent models are awkward to override cleanly, and a fork guarantees you re-resolve this on v4.