Advanced Nova Media Library Laravel Package

Getting Started

The 3.0.0 release is a compatibility major: it targets the current Laravel Nova and spatie/laravel-medialibrary releases. Treat it as an upgrade assessment first, not a drop-in patch.

1. Check the package’s composer.json constraints before upgrading. You will likely need a current Nova major, spatie/laravel-medialibrary v11+, PHP 8.2+, and a supported Laravel version. Confirm this against your app before running composer update.
2. Update the package and its peer dependencies together:

   composer require <vendor>/<package>:^3.0 --with-all-dependencies
   

3. Re-publish and review any package config, then run migrations if the package or Media Library migrations changed:

   php artisan vendor:publish --tag=<package-config>
   php artisan migrate
   

4. Ensure your model uses Spatie\MediaLibrary\InteractsWithMedia and implements registerMediaCollections() / registerMediaConversions().
5. Add the package’s Nova field to a resource and point it at a registered collection:

   use <Vendor>\<Package>\<MediaField>;
   
   public function fields(NovaRequest $request)
   {
       return [
           <MediaField>::make('Images')
               ->collection('images')
               ->multiple()
               ->accept('image/*')
               ->maxFiles(10),
       ];
   }
   

Look first at the package README, CHANGELOG.md, and upgrade notes for 3.0.0, then inspect the field class and any published config. The first practical use case is a single image or avatar upload on a Nova resource, with one thumbnail conversion defined in the model.

Implementation Patterns

Single-file and multi-file collections. Define the collection once in the model and reuse the exact same name in the Nova field. For a single avatar:

public function registerMediaCollections(): void
{
    $this->addMediaCollection('avatar')->singleFile();
}

Then use the Nova field with ->collection('avatar') and without ->multiple(). For galleries, use ->multiple() and enforce limits with ->maxFiles().

Conversions belong in the model, not the field. Register conversions in registerMediaConversions() and reference the conversion name from the Nova field where previews are supported. This keeps URLs, API output, and Nova previews consistent.

Disk and visibility per collection. Configure the disk on the model collection and mirror it on the field when the field supports it. This matters for S3, private buckets, and environments where local and production storage differ. Keep private media out of public previews or render it through temporary URLs.

Validation at the Nova layer. Use field rules for file type and size, for example ->rules('required', 'image', 'max:2048'), and combine with ->creationRules() / ->updateRules() when uploads are mandatory only on create. Keep server-side Media Library validation in the model as well if uploads can arrive outside Nova.

Admin-only versus application uploads. The Nova field is an admin UI convenience. For front-end or API uploads, use Media Library directly (addMediaFromRequest, addMediaFromDisk, etc.) and let Nova manage existing media. This avoids coupling public upload flows to a Nova field.

Queued conversions. If conversions are queued in the model, a worker must be running or Nova previews will appear missing after upload. This is common in production and easy to misdiagnose as a broken field.

Lifecycle hooks. Use Nova field visibility methods (->hideFromIndex(), ->onlyOnForms(), ->download()) to keep resource tables readable. For custom metadata, use Media Library custom properties from the model or the field’s supported property API, and expose them through accessors rather than duplicating logic in Nova.

Gotchas and Tips

• 3.0.0 is a compatibility break. The release note explicitly says it tracks the latest Nova and Spatie Media Library. Expect changed peer constraints and possible field API changes. Test create, update, delete, reorder, and conversion regeneration before rolling out.
• Collection name mismatches fail quietly. If the Nova field writes to a collection not registered on the model, uploads may succeed while conversions, URLs, or cleanup behave unexpectedly. Keep collection names in constants or a shared config.
• Conversion renames do not regenerate old files. After changing conversion names or dimensions, run the Media Library regenerate command and verify existing records.
• Disk changes can orphan media. Moving from local to S3, or changing visibility, requires a migration plan for existing files and database paths. Do not assume Nova previews will continue to work unchanged.
• Temporary uploads need configuration. Large uploads can hit PHP upload_max_filesize / post_max_size, Livewire temporary upload limits, or the Media Library temporary disk configuration. Check these before debugging the field itself.
• Private disks break naive previews. If a collection is private, Nova’s image preview may not load unless the field or your accessor generates temporary URLs. Verify download behavior separately from preview behavior.
• Clear caches after upgrading. Run php artisan config:clear, re-publish config if needed, and restart queue workers. Stale config is a common cause of “the upgrade did nothing” reports.
• Extension points: customize the Media model, add media collections per tenant or model type, override field methods for custom UI, and use model accessors for canonical URLs. Keep these customizations outside vendor files so the next major upgrade remains tractable.