File Picker Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require anil/file-picker
   

   Publish config and migrations:

   php artisan vendor:publish --provider="Anil\FilePicker\FilePickerServiceProvider"
   php artisan migrate
   

2. Basic Usage Add the Livewire component to your Blade view:

   @livewire('file-picker', ['model' => 'Post', 'field' => 'image'])
   

   Configure the field in your model:

   use Anil\FilePicker\Traits\HasFilePicker;
   
   class Post extends Model
   {
       use HasFilePicker;
   }
   

3. First Use Case Trigger the picker in a form:

   <x-file-picker-input wire:model="post.image" />
   

   The modal will open, allowing selection of files from the media library or uploads.

Implementation Patterns

Core Workflows

1. Media Library Integration

   • Use FilePicker::getFiles() to fetch paginated files with filters:

     $files = FilePicker::getFiles()->search('logo')->type('image')->paginate(10);
     

   • Bind to Livewire properties for real-time updates:

     public $selectedFiles = [];
     
     public function updatedSelectedFiles()
     {
         $this->validateEach($this->selectedFiles, [
             '*.file' => 'required|file|mimes:jpeg,png',
         ]);
     }
     

2. Upload Handling

   • Configure upload rules in config/file-picker.php:

     'upload_rules' => [
         'image' => ['max:10240', 'mimes:jpeg,png,svg'],
         'document' => ['max:5120', 'mimes:pdf,docx'],
     ],
     

   • Handle uploads via Livewire events:

     protected $listeners = ['fileUploaded' => 'handleUploadedFile'];
     
     public function handleUploadedFile($file)
     {
         $this->store()->files()->create([
             'user_id' => auth()->id(),
             'path' => $file->path(),
             'mime' => $file->mime(),
             'size' => $file->size(),
         ]);
     }
     

3. File Selection Patterns

   • Single file selection (default):

     <x-file-picker-input wire:model="post.thumbnail" mode="single" />
     

   • Multiple files with max limit:

     <x-file-picker-input wire:model="gallery.files" mode="multiple" max_files="5" />
     

4. Customizing the UI

   • Override Blade components in resources/views/vendor/file-picker/.
   • Extend CSS via config/file-picker.styles:

     'styles' => [
         'primary' => '#3b82f6',
         'background' => '#f8fafc',
     ],
     

5. Programmatic File Management

   • Add tags to files:

     $file->tags()->attach(['logo', 'brand']);
     

   • Move files between folders:

     $file->update(['folder_id' => $newFolder->id]);
     

Gotchas and Tips

Common Pitfalls

1. File Validation Mismatch

   • Ensure upload_rules in config match your model validation. Discrepancies cause silent failures.
   • Fix: Use wire:ignore on the input to debug:

     <input wire:ignore type="file" wire:model="fileInput">
     

2. Duplicate Detection Conflicts

   • SHA-256 hashing may reject identical files if reuse strategy is set. Test with:

     FilePicker::setDuplicateStrategy('allow'); // Temporarily override
     

3. Storage Quota Exceeded

   • Global quotas halt uploads. Check with:

     if (FilePicker::isQuotaExceeded()) {
         toast('Storage full!', 'error');
     }
     

4. Livewire Property Binding

   • Avoid binding to arrays directly. Use intermediate properties:

     // Bad: wire:model="post.images"
     // Good:
     public $tempImages = [];
     public function updatedTempImages()
     {
         $this->post->images = $this->tempImages;
     }
     

5. Folder Permissions

   • Folders inherit parent permissions. Reset with:

     $folder->update(['permissions' => 'rw']); // Read-write for all
     

Debugging Tips

• Log Upload Events Add to AppServiceProvider:

  FilePicker::onUploading(function ($file) {
      Log::debug('Uploading:', ['name' => $file->getClientOriginalName()]);
  });
  

• Inspect FilePicker State Use Tinker to check:

  php artisan tinker
  >>> \Anil\FilePicker\Facades\FilePicker::getStats();
  

• Clear Cached Views If UI breaks after config changes:

  php artisan view:clear
  php artisan cache:clear
  

Extension Points

1. Custom File Types Extend the FileType class:

   namespace App\Extensions;
   
   use Anil\FilePicker\Contracts\FileType;
   
   class CustomType implements FileType
   {
       public function getMimes(): array { return ['application/x-custom']; }
       public function getIcon(): string { return '🎯'; }
   }
   

   Register in config/file-picker.php:

   'custom_types' => [
       'custom' => \App\Extensions\CustomType::class,
   ],
   

2. Pre-Signed URLs for Direct Uploads Use the FilePicker::generateUploadUrl() method to create temporary S3 URLs:

   $url = FilePicker::generateUploadUrl($file->hash(), $file->mime());
   // Pass to frontend for direct upload
   

3. Webhook Triggers Listen for file events via FilePicker::on* methods:

   FilePicker::onFileDeleted(function ($file) {
       // Sync with external service
   });
   

4. Override Default Storage Bind custom storage to the File model:

   use Anil\FilePicker\Models\File;
   use League\Flysystem\Filesystem;
   
   File::addGlobalScope('customStorage', function (Builder $builder) {
       $builder->getQuery()->from(new Filesystem(...));
   });