Imageconverterbundle Laravel Package

Getting Started

Minimal path from install to first working image field:

1. composer require <vendor>/<package> (v1.1.0), then php artisan vendor:publish and pick the package's config/migrations/assets tags.
2. php artisan migrate — the relational mapping relies on the package's media/attachment table.
3. Publish the front-end assets: the JS image conversion added in 1.1.0 ships as a new asset file, so a stale published public/vendor/... directory will silently leave conversion off.
4. Clear caches: php artisan config:clear && php artisan view:clear (and optimize:clear on cached deploys).

Where to look first

• The published config file — it holds the conversion settings (target format/quality) and the media model / disk bindings.
• The form field or component class that renders the picker; that's the seam you'll extend for custom behaviour.
• php artisan route:list | grep <vendor> — the "choose existing image" modal is backed by an endpoint; knowing its name and middleware is what you'll debug most often.

First use case

Add an image to an existing Eloquent model: attach the package's field to your form, point it at the relation, upload one image, save, and render it in a Blade view. That single loop exercises upload, storage, the pivot/relation write, and the URL helper — if all four work, the rest of the package will behave.

Implementation Patterns

Two attach paths, one field. v1.1.0's modal gives users a choice: pick an existing media record or upload a new one. Model this in your form as a single field whose value is a media identifier, and let the package resolve "existing vs new" server-side. Don't build two separate form inputs — you'll end up with two code paths for validation and two for cleanup.

Reuse over re-upload. The real payoff of the existing-image picker is deduplication: a hero image used on ten pages should be one row. When writing queries, resolve through the relation and eager-load the media (with('image')) so listing pages don't N+1 on thumbnails.

Client-side conversion is an optimisation, not a guarantee. Treat the JS converter as a bandwidth/latency win. Keep server-side validation and (ideally) a server-side conversion or at least dimension/size checks for API and non-browser uploads. If your app accepts uploads from anywhere other than the package's form, JS conversion never runs.

Configure conversion once, centrally. Put target format and quality in the config file rather than per-field, so a future format change (e.g. AVIF) is a one-line deploy. If different fields need different treatment, prefer a named preset in config over inline overrides scattered across resources.

Integration with existing media. If you're adopting the package on a model that already has an image_path column, write a one-off command that imports legacy files into the package's media table and rewrites the relation — do this before swapping the form field, so you can roll back independently.

Testing pattern. Feature tests should post a real file via UploadedFile::fake()->image(...); that exercises the server path. Anything that depends on the JS converter needs a browser test (Dusk/Pest browser) or a unit test against the converter's input/output contract — PHPUnit alone will never execute it.

Gotchas and Tips

Mime/extension mismatch after conversion. A user uploads photo.png, the browser converts to WebP, and your mimes:png,jpg rule rejects the request. Validate against what arrives, not what the user picked, and widen the rule to include the configured target format.

Client-side conversion strips EXIF — including orientation. Canvas re-encoding drops orientation metadata, so phone photos rotated by EXIF can arrive sideways, or correctly rotated depending on the browser's createImageBitmap behaviour. Test with a real portrait phone photo; don't assume.

Browser memory limits. Canvas conversion of very large images (roughly >16MP on mobile Safari) can fail silently or return a blank canvas. Cap input dimensions before conversion, or fall back to uploading the original and converting server-side.

Stale published assets after upgrade. The most common "the new feature doesn't work" report after 1.1.0: assets were published at 1.0 and never refreshed. Re-publish with --force and bust any CDN cache in the same deploy.

Authorization on the picker endpoint. The "choose existing image" route exposes a list of media records. Confirm it's behind the same middleware and policy checks as the rest of your admin surface — a field that renders fine can still leak a full media library to a lower-privileged role.

Morph map / relation name drift. If you use a morph map, the package must resolve the same alias your models register. A mismatch shows up as an empty picker with no error, only a null relation.

Queue workers after upgrade. If image conversions or thumbnails are queued, restart workers on deploy — old workers hold the previous config and class definitions in memory.

Extension points worth knowing. The converter is usually swappable via config (bind your own implementation for a different pipeline), the picker's view is publishable for layout changes, and the media model can be subclassed if you need extra columns. Reach for those before forking the package.

Debugging checklist when an image doesn't appear: (1) is the file on the configured disk, Storage::disk(...)->exists($path); (2) does the relation return a row; (3) does the URL helper produce a path that matches your APP_URL/CDN config; (4) is the asset published. In that order — it saves guessing.