Media Laravel Package

Getting Started

• Require the package via Composer and pin to ^0.7 (or an exact version) — this is pre-1.0, so treat minor bumps as potentially breaking and read each release.
• Publish both config and migrations (vendor:publish), not just config.
• Run migrations before any app code touches media. As of v0.7.1 the package no longer creates the app/root media folder eagerly; it waits until the media folder table exists. On a fresh install the correct order is: publish → migrate → create/seed folders → upload.
• Migrations as of v0.7.3 also include 2026_10_01_000001_move_generated_media_directories, which relocates .thumbnails/.variants to _thumbnails/_variants and rewrites stored paths. It is idempotent and a no-op on fresh installs, but it is the reason a straight php artisan migrate is now a required upgrade step, not just a fresh-install step.
• Point the package at a filesystem disk and root path in the published config.
• First use case to validate your setup: create a folder, upload a file, attach it to a model via the media relationship, then resolve and stream/return its URL — and load a thumbnail URL, since generated-directory paths are the part most likely to be wrong after an upgrade.

Where to look first: the migrations (particularly the media folder table and move_generated_media_directories), the Media model, the service provider (this is where the deferred folder creation lives), and the config file. Those files explain most behaviour you'll encounter day-to-day.

Implementation Patterns

• Attach-to-model is the core workflow. Media hangs off models through the package's relationship; use the provided add/attach helpers rather than writing files directly to the disk, so records and files stay in sync.
• Provision folders explicitly. Because v0.7.1 defers folder creation until migration, don't rely on an implicit root folder. Create the folder tree in a seeder, an install command, or an app-level migration so every environment converges to the same state.
• Treat php artisan migrate as part of the upgrade runbook, not just deploy setup. Since v0.7.3 the generated-media path migration is your only supported way to move .thumbnails/.variants; run it in CI, staging, and prod, then verify a thumbnail renders.
• Test setup needs an explicit step. With RefreshDatabase, migrations run but your root folder may not exist at the moment a test uploads. Add a setup helper (or a base test case) that creates the folder tree after migration and before the first upload.
• Existing apps are unaffected by the folder change once the migration has run — the deferral only bites on new databases. New environments (CI, fresh staging, new dev machines) are where you'll see the difference.
• Check for aiDocument usage before upgrading. The relation was removed from the Media model as unused. If your code called $media->aiDocument you now get a missing-relation error; replace it with your own relation or pivot.
• Migration ordering matters if any of your own migrations reference the media folder table or the generated-media path columns — ensure they run after the package's migrations (the path migration is timestamped 2026_10_01).
• Post-migration verification: after the path rewrite, re-render a page that serves thumbnails and check the stored path column values start with _thumbnails/_variants, not a dot-prefixed directory.

Gotchas and Tips

• Upgrading from before v0.6.6 straight to v0.7 leaves thumbnails in dot-directories (.thumbnails, .variants), which the stock Forge nginx config refuses to serve — you get 403s on images that exist on disk. v0.7.3 restores the migration that fixes this; if you upgraded in the v0.7.0–v0.7.2 window, run php artisan migrate again to pick it up.
• The v0.7.1 folder-creation change is a patch-level version but a behavioural change. Anything that assumed the folder exists immediately after composer install or package discovery will break on a fresh database.
• The path migration rewrites stored paths in the database but cannot fix things you cached elsewhere: CDN entries, full URLs baked into HTML/sitemaps, image-transform caches, or your own tables that copied the old .thumbnails path. Purge caches and regenerate derived URLs after running it.
• Search your own code for hardcoded .thumbnails / .variants strings — config overrides, blade templates, and queue jobs are the usual suspects. They will silently keep pointing at the old, now-empty directory.
• "Folder not found"-style upload errors on a fresh install almost always mean app code (a seeder, a bootstrap hook, a console command) ran before migrations. Reorder rather than debugging the storage layer.
• Keep an eye on the service provider if you need eager folder creation — that's the cleanest extension point to restore the old behaviour for your app without forking the package.
• Grep your application for aiDocument before upgrading. If it's unused, the removal is a no-op; if it isn't, the failure surfaces at runtime as a missing method/relation rather than at install time.
• Pin exact versions in composer.json while the package is 0.x, and skim release notes for relationship/model changes and re-added or amended migrations — both break silently.