Filemanager Laravel Package

Getting Started

Minimal Steps

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. Include Component: Add to your Blade template:

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

3. Tailwind Configuration (for production): Update tailwind.config.js:

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

4. First Use Case:

   • Upload files via drag-and-drop or file picker.
   • Organize files into folders (create/edit/delete).
   • Preview images/videos directly in the UI.

Implementation Patterns

Core Workflows

1. File Uploads:

   • Use the built-in drag-and-drop or file picker.
   • Leverage Spatie’s MediaLibrary for storage (e.g., S3, local).
   • Example:

     // In a Livewire component
     public function uploadFiles()
     {
         $this->validate(['files' => 'required|array']);
         foreach ($this->files as $file) {
             $this->storeMedia($file); // Uses Spatie's MediaLibrary
         }
     }
     

2. Folder Management:

   • Create nested folders via the UI or API:

     // API Example (POST /api/filemanager/v1/folders)
     {
         "name": "projects",
         "parent_id": null // Root folder
     }
     

   • Traverse folders programmatically:

     use LivewireFilemanager\Filemanager\Models\Folder;
     $folder = Folder::with('children')->find(1);
     

3. File Access:

   • Serve files publicly via route:

     Route::get('{path}', [FileController::class, 'show'])
          ->where('path', '.*')
          ->name('assets.show');
     

   • Generate shareable URLs in the UI (copy-to-clipboard feature).

4. API Integration:

   • Authenticate with Sanctum:

     Route::middleware('auth:sanctum')->group(function () {
         Route::apiResource('folders', FolderController::class);
     });
     

   • Example API call (JavaScript):

     axios.post('/api/filemanager/v1/files', {
         file: fileInput.files[0],
         folder_id: 1
     }, {
         headers: { 'Authorization': `Bearer ${userToken}` }
     });
     

5. Livewire Component Customization:

   • Extend the component:

     <x-livewire-filemanager
         :allowed-file-types="['jpg', 'png', 'pdf']"
         :max-file-size="5" // MB
     />
     

   • Override views (e.g., resources/views/vendor/livewire-filemanager/filemanager.blade.php).

Integration Tips

1. Queue Thumbnails:

   • Configure QUEUE_CONNECTION in .env for async thumbnail generation:

     QUEUE_CONNECTION=database
     

   • Run queue workers:

     php artisan queue:work
     

2. ACL Setup:

   • Publish config and enable ACL:

     php artisan vendor:publish --tag=livewire-filemanager-config
     

     Update livewire-filemanager.php:

     'acl_enabled' => true,
     

   • Restrict media access by user:

     use LivewireFilemanager\Filemanager\Traits\HasMediaOwner;
     class User extends Authenticatable {
         use HasMediaOwner;
     }
     

3. Multilingual Support:

   • Load translations dynamically:

     app()->setLocale('es'); // Spanish
     

   • Add custom translations to resources/lang/vendor/livewire-filemanager.

4. Dark Mode:

   • Toggle via UI or force dark mode in config:

     'default_dark_mode' => true,
     

5. Testing:

   • Use Testbench for API tests:

     $response = $this->actingAs($user)
         ->postJson('/api/filemanager/v1/files', [
             'file' => $file,
             'folder_id' => 1
         ]);
     

Gotchas and Tips

Pitfalls

1. HTTPS Requirement:

   • Copy-to-clipboard URLs fail without HTTPS. Use a self-signed cert for local dev:

     openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
     

   • Configure Laravel to trust the cert:

     // config/trustedproxies.php
     'proxies' => '127.0.0.1',
     

2. Queue Delays:

   • Thumbnails may not appear immediately if using QUEUE_CONNECTION=database. Monitor workers:

     php artisan queue:failed-table
     

3. File Permissions:

   • Ensure storage directories are writable:

     chmod -R 775 storage/app/public
     

4. API Authentication:

   • Sanctum tokens must be included in API requests. Test with:

     php artisan sanctum:install
     

5. Tailwind CDN in Production:

   • Replace @filemanagerStyles with local Tailwind in app.blade.php:

     <link href="{{ mix('css/app.css') }}" rel="stylesheet">
     

Debugging

1. Logs:

   • Enable Spatie Media Library logging:

     'logging' => true,
     

     in config/medialibrary.php.

2. Livewire Errors:

   • Check browser console for AlpineJS/Tailwind conflicts. Isolate by disabling other JS:

     @push('scripts')
         @filemanagerScripts
     @endpush
     

3. API Issues:

   • Validate Sanctum middleware:

     Route::middleware('auth:sanctum')->group(function () {
         // API routes
     });
     

   • Test API with Postman or Laravel’s HTTP client:

     $response = Http::withToken($user->createToken('test')->plainTextToken())
         ->post('/api/filemanager/v1/files', ['file' => $file]);
     

Extension Points

1. Custom Storage:

   • Extend Spatie’s Media model to support custom drivers:

     class CustomMedia extends Media {
         public function registerConversions(ConversionManager $manager)
         {
             $manager->addConversion('custom_thumb')
                 ->width(200)
                 ->height(200);
         }
     }
     

2. Event Listeners:

   • Hook into file/folder events:

     use LivewireFilemanager\Filemanager\Events\FileUploaded;
     
     FileUploaded::listen(function ($event) {
         Log::info("File uploaded: {$event->file->name}");
     });
     

3. UI Customization:

   • Override Blade components:

     cp -r vendor/livewire-filemanager/filemanager/resources/views/vendor/livewire-filemanager resources/views/vendor/
     

   • Modify filemanager.blade.php to add buttons or fields.

4. Validation Rules:

   • Extend file upload validation:

     use LivewireFilemanager\Filemanager\Rules\FileType;
     
     $rules = [
         'files' => ['required', 'array', new FileType(['jpg', 'png'])],
     ];
     

5. Dark Mode Toggle:

   • Add a global toggle via AlpineJS:

     <button x-on:click="darkMode = !darkMode">
         Toggle Dark Mode
     </button>
     

     Update filemanager.blade.php to respect darkMode state.

Configuration Quirks

1. Folder Model:

   • The Folder model uses fillable = ['name', 'path', 'parent_id']. Add custom fields via:

     protected $fillable = ['name', 'path', 'parent_id', 'custom_field'];
     

2. Media Model:

   • Ensure config('medialibrary.media_model') points to LivewireFilemanager\Filemanager\Models\Media.

3. Queue Workers:

   • Thumbnails use dispatchSync by default. For production, set:

     'thumbnail_dispatch_sync' => false,
     

     in livewire-filemanager.php.

4. Public URL Route:

   • The assets.show route conflicts with Laravel’s default routes. Use a namespace:

     Route::prefix('fm')->name('fm.')->group(function ()