Advanced Nova Media Library Laravel Package

Getting Started

First Steps

1. Installation

   composer require ebess/advanced-nova-media-library
   php artisan vendor:publish --provider="EBESS\AdvancedNovaMediaLibrary\AdvancedNovaMediaLibraryServiceProvider"
   php artisan nova:publish
   

   • Publish the config (config/advanced-nova-media-library.php) and Nova assets.

2. Configuration

   • Update config/advanced-nova-media-library.php to define:
     • Allowed file types (e.g., ['images/*', 'video/*']).
     • Disk settings (e.g., default_disk: 'public').
     • Thumbnail generation rules (if using Spatie’s media-library).
   • Ensure spatie/laravel-media-library is installed and configured in your Laravel app.

3. Basic Usage

   • Add the tool to a Nova resource:

     use EBESS\AdvancedNovaMediaLibrary\AdvancedNovaMediaLibrary;
     
     public static $mediaFields = [
         'images' => AdvancedNovaMediaLibrary::make('Images', 'images')
             ->onlyImages()
             ->maxSize(5),
     ];
     

   • Run php artisan nova:serve and visit the Nova dashboard to see the new media field.

First Use Case: Uploading Images

1. Create a Nova resource with $mediaFields.
2. Upload files via the Nova UI—drag-and-drop or manual selection.
3. Files are stored on the configured disk (e.g., public), and thumbnails are generated automatically (if Spatie’s media-library is set up).

Implementation Patterns

1. Field Customization

• Restrict File Types:

  AdvancedNovaMediaLibrary::make('Documents', 'documents')
      ->onlyFiles()
      ->allowedFileExtensions(['pdf', 'docx']);
  

• Limit Uploads:

  ->minSize(1)
  ->maxSize(10);
  

• Custom Disk:

  ->disk('s3');
  

2. Integration with Spatie Media Library

• Access Media in Model:

  $model->images->first()->getUrl(); // Returns full URL
  $model->images->first()->getPath(); // Returns disk path
  

• Custom Thumbnails: Configure Spatie’s media-library to generate thumbnails (e.g., convert or imagick drivers). The Nova tool will respect these settings.

3. Workflow: Bulk Uploads

• Use the "Add Multiple" button in Nova to upload multiple files at once.
• Validate uploads server-side by overriding resolveForDisplay() or resolveForUpdate() in your resource.

4. Dynamic Fields

• Conditionally show/hide media fields based on model state:

  public function fields(Request $request)
  {
      $fields = [...];
      if ($request->has('is_featured')) {
          $fields[] = AdvancedNovaMediaLibrary::make('Featured Image', 'featured_image')
              ->onlyImages()
              ->minSize(1);
      }
      return $fields;
  }
  

5. API Integration

• Expose media URLs via Nova’s API for frontend use:

  public function jsonApiFields(Request $request)
  {
      return [
          'media_url' => function () {
              return $this->images->first()?->getUrl();
          },
      ];
  }
  

Gotchas and Tips

Pitfalls

1. Disk Mismatch:

   • Ensure the Nova tool’s disk setting matches your Spatie media-library config. Files uploaded via Nova won’t appear in the model if disks differ.
   • Fix: Verify config/advanced-nova-media-library.php and config/filesystems.php.

2. Thumbnail Generation Failures:

   • If thumbnails aren’t generating, check:
     • Spatie’s media-library is configured with convert or imagick.
     • The spatie/laravel-medialibrary package is installed.
   • Fix: Run php artisan media:generate-thumbnails manually.

3. Permission Issues:

   • Nova may fail to upload files if the storage disk lacks write permissions.
   • Fix: Run chmod -R 775 storage/app/public (adjust as needed).

4. Large File Uploads:

   • Nova’s default max_file_upload (in config/nova.php) may block large files.
   • Fix: Increase max_file_upload (e.g., 10485760 for 10MB) and ensure PHP’s upload_max_filesize and post_max_size are higher.

5. Caching:

   • Nova caches field definitions. Clear the cache after changing field configurations:

     php artisan nova:cache-clear
     

Debugging Tips

• Log Uploads: Add a resolved() method to your resource to log media uploads:

  public function resolved()
  {
      \Log::info('Media uploaded:', ['files' => $this->images]);
  }
  

• Check Disk Contents: Verify files exist on the configured disk:

  ls storage/app/public
  

• Nova Tool Logs: Enable Nova’s debug mode in config/nova.php:

  'debug' => env('NOVA_DEBUG', false),
  

Extension Points

1. Custom Validation: Override resolveForUpdate() to validate files before saving:

   public function resolveForUpdate(Request $request)
   {
       $data = parent::resolveForUpdate($request);
       if (isset($data['images'])) {
           foreach ($data['images'] as $file) {
               if ($file->getClientOriginalExtension() !== 'jpg') {
                   throw new \Exception('Only JPG files allowed.');
               }
           }
       }
       return $data;
   }
   

2. Custom Storage Paths: Dynamically set storage paths per model:

   AdvancedNovaMediaLibrary::make('Profile Media', 'media')
       ->disk(function ($model) {
           return 'profiles/' . $model->user_id;
       });
   

3. Event Listeners: Trigger actions on media uploads (e.g., send notifications):

   use EBESS\AdvancedNovaMediaLibrary\Events\MediaUploaded;
   
   MediaUploaded::dispatch($model, $fieldName, $files);
   

   Listen in EventServiceProvider:

   protected $listen = [
       MediaUploaded::class => [YourListener::class],
   ];
   

4. Custom Thumbnail Drivers: Extend Spatie’s Media model to support additional thumbnail drivers:

   // app/Models/Media.php
   use Spatie\MediaLibrary\HasMedia;
   use Spatie\MediaLibrary\InteractsWithMedia;
   
   class Media extends \Spatie\MediaLibrary\Models\Media
   {
       public function registerConversions(): void
       {
           $this->addConversion('custom_thumb')
               ->width(200)
               ->height(200)
               ->driver('imagick'); // or 'convert'
       }
   }
   

Pro Tips

• Batch Processing: Use Nova’s Action system to process media in bulk:

  public function actions(Request $request)
  {
      return [
          (new ProcessMedia($request))->canSee(),
      ];
  }
  

  class ProcessMedia extends Action
  {
      public function handle($model)
      {
          foreach ($model->images as $media) {
              // Process each file (e.g., resize, optimize)
          }
      }
  }
  

• Soft Deletes: If using Spatie’s soft deletes, ensure Nova’s media field respects it:

  AdvancedNovaMediaLibrary::make('Media', 'media')
      ->softDeletes();
  

• Localization: Translate field labels and buttons by publishing Nova’s language files:

  php artisan vendor:publish --tag=nova-lang