Filemanager Laravel Package

Getting Started

Minimal Setup for First Use

1. Installation:

   composer require livewire-filemanager/filemanager
   php artisan vendor:publish --tag=livewire-filemanager-migrations
   php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-migrations"
   php artisan migrate
   

2. Basic Integration: Add the component to a Blade view with Tailwind/AlpineJS:

   @filemanagerStyles
   <x-livewire-filemanager />
   @filemanagerScripts
   

3. First Use Case:

   • Upload files via drag-and-drop or the file picker.
   • Organize files into folders using the tree view.
   • Copy file URLs directly from the UI (requires HTTPS).

Implementation Patterns

Core Workflows

1. File Management:

   • Livewire Component: <x-livewire-filemanager /> handles all CRUD operations.
   • Drag-and-Drop: Native support for bulk uploads (trigger filemanager.upload Livewire event).
   • Folder Hierarchy: Nested folders with breadcrumbs for navigation.

2. API Integration:

   • REST Endpoints: /api/filemanager/v1/ for programmatic access.
   • Authentication: Sanctum-protected routes (configure in config/livewire-filemanager.php).
   • Example API Call:

     axios.post('/api/filemanager/v1/folders', { name: 'NewFolder' }, {
       headers: { 'Authorization': `Bearer ${userToken}` }
     });
     

3. Customization:

   • Tailwind Overrides: Extend styles via app.css or tailwind.config.js:

     // tailwind.config.js
     module.exports = {
       content: [
         './resources/**/*.blade.php',
         './vendor/livewire-filemanager/filemanager/resources/views/**/*.blade.php',
       ],
     };
     

   • Component Extensions: Override Livewire methods in a custom component:

     class CustomFilemanager extends \LivewireFilemanager\Filemanager\Livewire\Filemanager {
       public function customUpload($files) {
         // Pre-process files before upload
         $this->upload($files);
       }
     }
     

4. Public File Access:

   • Route files via FileController:

     Route::get('{path}', [\LivewireFilemanager\Filemanager\Http\Controllers\Files\FileController::class, 'show'])
          ->where('path', '.*')->name('assets.show');
     

Integration Tips

• Spatie Media Library: Use the package’s Media model for consistency:

  use LivewireFilemanager\Filemanager\Models\Media;
  $media = Media::find(1)->getUrl();
  

• Queue Thumbnails: Dispatch thumbnail generation asynchronously:

  config(['livewire-filemanager.thumbnail_queue' => true]);
  

• ACL Setup: Enable role-based access:

  // config/livewire-filemanager.php
  'acl_enabled' => true,
  

  Publish Spatie’s config and set media_model to LivewireFilemanager\Filemanager\Models\Media.

Gotchas and Tips

Pitfalls

1. HTTPS Requirement:

   • Copying file URLs fails without HTTPS. Use a reverse proxy (e.g., Nginx) or configure Laravel’s APP_URL properly.

2. Thumbnail Queue:

   • Thumbnails default to queue processing. For local development, set:

     QUEUE_CONNECTION=sync
     

3. Tailwind CDN in Production:

   • Avoid @filemanagerStyles in production. Instead, include the package’s CSS via Tailwind’s content paths.

4. ACL Misconfiguration:

   • If ACL is enabled but files are still accessible, verify:
     • media_model in config/medialibrary.php points to LivewireFilemanager\Filemanager\Models\Media.
     • Users have the correct permissions via Laravel’s auth system.

5. File Size Limits:

   • Default PHP upload_max_filesize and post_max_size may block large uploads. Adjust in php.ini or use chunked uploads:

     config(['livewire-filemanager.chunk_uploads' => true]);
     

Debugging

• Livewire Events: Listen for events like filemanager.uploaded:

  Livewire::listen('filemanager.uploaded', function ($event) {
    Log::info('File uploaded:', $event['file']);
  });
  

• API Errors: Check Sanctum tokens and CORS settings if API calls fail:

  // config/cors.php
  'paths' => ['api/filemanager/v1/*'],
  'allowed_methods' => ['*'],
  'allowed_origins' => ['*'], // Restrict in production
  

Extension Points

1. Custom Storage: Override the Storage facade binding:

   $this->app->bind(\Illuminate\Contracts\Filesystem\Filesystem::class, function () {
     return \Illuminate\Support\Facades\Storage::disk('s3');
   });
   

2. File Validation: Extend the Filemanager Livewire class to add custom rules:

   protected function rules() {
     return [
       'files.*' => ['required', 'file', 'mimes:jpg,png,pdf', 'max:10240'], // 10MB limit
     ];
   }
   

3. Event Listeners: Listen for file/folder events:

   use LivewireFilemanager\Filemanager\Events\FileUploaded;
   
   FileUploaded::listen(function (FileUploaded $event) {
     // Send notification or log metadata
   });
   

4. Dark Mode: Force dark mode via config:

   'dark_mode' => env('APP_DARK_MODE', false),
   

Pro Tips

• Bulk Operations: Use the API for batch processing:

  axios.post('/api/filemanager/v1/files/bulk', {
    files: [1, 2, 3],
    action: 'delete'
  });
  

• Localization: Override translations in resources/lang/vendor/livewire-filemanager:

  'copy_url' => 'Copied link to clipboard!',
  

• Performance: Disable unnecessary features in config:

  'thumbnail_generation' => false, // Skip thumbnails for non-image files