Laravel Eloquent Images Laravel Package

Getting Started

• Require the package (composer require zingimmick/laravel-eloquent-images) and confirm your PHP/Laravel versions are inside the constraint — this release line was built against a modernized toolchain (setup-php 2.12, Rector 0.10, coding-standard v4), so it expects a reasonably current PHP.
• Publish and inspect the migration and config before running php artisan migrate. The 1.1.0 Fix table name change means the shipped migration may reference a different table name than the 0.2.0 line did. Read the file rather than trusting memory.
• Add the package trait to a model, define the image attributes/conversions that model should expose, and save one image end-to-end before wiring anything else. The first use case is almost always "a User or Post has one avatar/cover, resized on demand" — get that visible in a Blade view first, then generalize.
• Where to look first: the migration (table/schema shape), the config file (storage disk, conversions, URL generation), then the trait source for the public method signatures. Those three tell you 90% of the day-to-day API.

Implementation Patterns

• Trait-per-model, conversions-per-attribute. Expect to declare conversions (thumbnail, hero, etc.) on the model or in config, then call a single save method passing an uploaded file or a URL. Keep conversion definitions close to the model so a reader doesn't have to cross-reference config.
• Form request → service method → model. Validate the upload in a FormRequest (image, mimes, max), pass the validated file into a small service or action, and let the trait handle persistence. This keeps controllers thin and makes image handling testable with UploadedFile::fake().
• Separate images table, so treat it as a relation. Because images live in their own table, eager-load the relation (with('images') or the per-attribute accessor's equivalent) on index pages. N+1 queries on a gallery listing is the most common performance regression with this shape of package.
• Ordering and "primary image". If the schema carries an order/position or primary flag, set it explicitly on save and sort deterministically in queries. Don't rely on insertion order — it breaks the moment you update an image in place.
• Deletion is your job, not the database's. Hook deleting/deleted on the model (or use an observer) to remove image rows and the underlying files on the disk. Foreign-key cascades clean rows but never touch storage.
• Queues for anything heavy. If conversions are generated eagerly, push them to a job so an upload request stays fast. If they're generated on demand at URL time, make sure the web server/cache in front of the app can absorb the first-hit cost.
• Storage disks. Point the package at a non-public or S3 disk via config rather than hardcoding public. For local dev, storage:link is still required if you serve directly from the public disk; for S3, confirm the URL generator respects your CDN or signed-URL settings.
• Integration tip: wrap image handling behind a small domain method ($post->replaceCover($file)) so if you later migrate to a different media package, only one method changes.

Gotchas and Tips

• The table name change is the one upgrade risk. If you're coming from 0.2.0, diff the published migration against the one in your repo and check for any raw queries, report builders, or admin tooling that reference the old name. Run the upgrade on a scratch database with real-shaped data before touching production.
• Version jump, not a patch. 0.2.0 → 1.1.0 is a major-line move. Pin the version, read the trait's method signatures after upgrading, and expect static-analysis (PHPStan/Psalm) to surface signature changes your IDE glosses over.
• Published-then-changed migrations never re-run. Laravel won't re-publish over an existing migration file, and a changed migration won't re-execute. If the table name fix matters to you, you need a new migration that renames, not a re-publish.
• Debugging missing images: check in this order — (1) is the row in the images table? (2) does the file exist on the configured disk (not the one you assumed)? (3) does the generated URL match your APP_URL/CDN host? Most "images are broken" reports are step 3, caused by a stale cache or a mismatched disk driver.
• Config caching bites. php artisan config:cache in deploy scripts means config edits silently don't apply until you re-cache. If a disk or conversion change "does nothing," this is why.
• Conversion regeneration is manual. Changing dimensions or quality in config does not retroactively regenerate existing derivatives. Plan a backfill command, or accept that old images keep old sizes.
• Extension points worth knowing: the config file for disk/conversion defaults, the model trait for overriding save/delete behavior, and model events/observers for cleanup. Prefer these over forking the package — the release cadence here is dependency-bump heavy, so forks get expensive to maintain.
• Don't read much into this changelog. 1.1.0 is overwhelmingly Dependabot bumps and CI noise (codecov, checkout, setup-php, coding-standard). The only user-facing item is the table name fix plus the modernization that comes with it. Treat the rest as "the project is maintained and its CI is tidy," not as new capability.