Irmoble Laravel Package

Getting Started

The package is at 0.1.1 — still pre-1.0, so treat the public API as unstable and pin the exact version in composer.json ("vendor/package": "0.1.1") rather than using a caret constraint. There is no prior assessment to diff against, so this first review is based on the 0.1.1 release, whose only documented change is a fix to the gallery field.

Minimal path to first value:

1. composer require vendor/package:0.1.1
2. Run the installer/publish step if the package ships one (php artisan vendor:publish --tag=...) and check for a config file controlling the storage disk, upload path, and thumbnail sizes.
3. Run migrations only if the package ships a table (many gallery fields store a JSON column on your own model instead — check the README before adding a migration).
4. Register the gallery field in one resource/form and upload two or three images through the UI.

Where to look first: the field class itself and its config/settings array. That is where disk, directory, accepted mime types, max file count, and reordering behaviour are usually defined, and it tells you more about day-to-day behaviour than the README.

First realistic use case: a Post or Product model with a gallery JSON column holding an ordered array of relative paths. Render it in the admin panel via the field, then hydrate it in your API resource with Storage::disk($disk)->url($path).

Implementation Patterns

Cast and shape the data deliberately. Confirm exactly what the field persists — an array of path strings, an array of objects with path/name/size, or IDs into a media table. Cast accordingly ('gallery' => 'array' or a custom cast), and write one accessor that returns fully-qualified URLs so views and API resources never build storage paths themselves. This single indirection is what makes a later move from local disk to S3 a config change instead of a refactor.

Keep disk configuration out of the field call. Define a gallery disk in config/filesystems.php (or reference FILESYSTEM_DISK) and let the field use it. Hardcoding 'disk' => 'public' in a resource class is the most common reason these fields break in staging.

Treat ordering as part of the contract. Galleries are almost always ordered. If the field supports drag-reorder, the order lives in the JSON array — so never sort() or array_filter() the collection before persisting without array_values(), or you will write sparse arrays and get gaps after the first delete.

Integration with forms and validation. Validate on the way in: 'gallery' => ['array', 'max:10'], 'gallery.*' => ['string'] (or image/mimes: rules if the field posts uploads rather than paths). Put the rule in a Form Request so the same constraints apply to the panel, an API endpoint, and any importer.

Cleanup on delete. Hook deleting/updated on the model to diff old vs. new gallery contents and remove orphaned files from the disk. Without this, the bucket fills silently and nobody notices until the invoice arrives.

Rendering. For Blade, loop the accessor and lazy-load with loading="lazy"; for APIs, expose both path and url so clients can pick. If you need responsive variants, check whether the package offers conversions/thumbnails; if not, generate them with a queue job at upload time rather than on request.

Testing. Use Storage::fake('gallery') and assert on the persisted JSON shape, not on the field's internal upload mechanics. The 0.1.1 fix is exactly the class of bug that a shape-assertion test would have caught on your side, so add one now while the surface area is small.

Gotchas and Tips

• 0.1.1 is a patch release fixing the gallery field. Upgrade from 0.1.0 promptly — a "gallery field fix" in a 0.x package often means the previously persisted data shape was wrong or partially written. After upgrading, spot-check existing records: re-save one gallery and diff the column before/after. If the shape changed, write a one-off backfill command rather than re-saving everything by hand.
• Patch releases in 0.x can still be breaking. Semver's stability guarantees do not apply below 1.0. Read the diff, not just the release note; one line of changelog can hide a signature change.
• Silent upload failures. Gallery fields typically upload asynchronously. If images vanish on save, check: disk write permissions, php artisan storage:link, the upload_max_filesize/post_max_size pair, and whether the field's temp directory is shared across queue workers.
• Livewire/Inertia temp files. If the field stages files before save, abandoned forms leave orphaned temp uploads. Look for a scheduled prune command or add one.
• N+1 on listing pages. Rendering a gallery column per row in an index table will hit the disk or a relations table per record. Either eager-load, cache the URLs, or disable the field's preview in index views.
• Extension points to check before forking: a custom FileAdder/upload handler, a ->conversion() or ->thumbnails() callback, and the field's path-resolution method. Overriding path resolution is usually enough to support a CDN or a non-standard directory layout without touching vendor code.
• Debugging tip: when a gallery field misbehaves, dd() the raw request payload in the field's fill/store method. Nine times out of ten the data arrives intact and the problem is in the model cast or the save pipeline — knowing which side is broken saves an hour.
• Watch the issue tracker for the next release. A field-level fix at this version suggests active development; if you are building on this package in production, keep an eye out for a 0.2.0 that may reorganise the field API.