Filament Url Image Uploader Laravel Package

Getting Started

Minimal Setup

1. Installation: Run composer require amjadiqbal/filament-url-image-uploader in your project.
2. Publish Config: Execute php artisan vendor:publish --provider="Amjadiqbal\FilamentUrlImageUploader\FilamentUrlImageUploaderServiceProvider" to publish assets (if needed).
3. First Use Case: Add the component to a Filament form:

   use Amjadiqbal\FilamentUrlImageUploader\UrlImageUploader;
   
   UrlImageUploader::make('image')
       ->directory('images')
       ->required()
       ->maxSize(5) // MB
       ->allowedExtensions(['jpg', 'png', 'svg']);
   

Where to Look First

• README: Focus on the Usage section for basic implementation.
• Documentation: Check devodocs for advanced features.
• Service Provider: Inspect config/filament-url-image-uploader.php for global defaults.

Implementation Patterns

Core Workflows

1. Form Integration:

   // In a Filament Resource Form
   public static function form(Form $form): Form
   {
       return $form
           ->schema([
               UrlImageUploader::make('hero_image')
                   ->directory('products/{$record->id}')
                   ->rules(['required', 'image']),
           ]);
   }
   

2. Dynamic Directories: Use closures for dynamic paths:

   UrlImageUploader::make('avatar')
       ->directory(fn (UploadedFile $file, ?Post $record) => "users/{$record->id}/avatars")
   

3. Model Binding:

   • Accessors: Normalize the response in your model:

     public function getImageUrlAttribute(): ?string
     {
         return $this->image ? Storage::url($this->image) : null;
     }
     

   • Mutators: Handle array responses:

     protected function castImage(): Attribute
     {
         return Attribute::make(
             get: fn ($value) => is_array($value) ? $value['image'] : $value,
             set: fn ($value) => is_array($value) ? $value : ['image' => $value],
         );
     }
     

4. Validation: Combine with Filament’s built-in validation:

   UrlImageUploader::make('thumbnail')
       ->rules([
           'required',
           'image',
           'dimensions:min_width=100,max_width=2000',
       ]);
   

Integration Tips

• Storage Disk: Override the default disk (e.g., S3) via config:

  'disk' => 's3',
  

• Preview Optimization: Use ->previewHeight(200) to control thumbnail size in the UI.
• Bulk Uploads: Chain with other components (e.g., FileUpload) for hybrid workflows:

  $form->schema([
      UrlImageUploader::make('remote_image'),
      FileUpload::make('local_image'),
  ]);
  

Gotchas and Tips

Pitfalls

1. Directory Permissions:

   • Ensure the target storage directory is writable. Use storage:link if accessing via public path.
   • Debug: Check Laravel logs for Permission denied errors when saving files.

2. URL Validation:

   • The package validates URLs but may fail on:
     • Non-HTTP(S) URLs (e.g., ftp://).
     • URLs with query strings (e.g., ?width=500). Use ->allowQueryStrings() to bypass.
   • Fix: Pre-process URLs in the form’s beforeValidate:

     $form->beforeValidate(function (Form $form) {
         $form->fillFormData([
             'image' => strtok($form->data['image'], '?'),
         ]);
     });
     

3. Caching Issues:

   • Previews may not update immediately due to browser caching. Force refresh or append a query string:

     ->previewUrl(fn ($record) => $record->image_url . '?t=' . time())
     

4. Model Sync:

   • If using hasMany relationships, ensure the uploader’s directory includes the relationship key:

     ->directory("posts/{$record->id}/attachments")
     

Debugging

• Log Raw Responses: Temporarily log the uploader’s output:

  ->afterStateUpdated(fn ($state, $set) => \Log::debug('Uploaded:', $state))
  

• Check Storage Paths: Verify files are saved to:

  ls storage/app/images/
  

• Test with telescope: Enable Laravel Telescope to inspect HTTP requests to remote URLs.

Extension Points

1. Custom Validation: Override validation logic via a service provider:

   UrlImageUploader::extend(function (UrlImageUploader $component) {
       $component->validationRules = [
           'required',
           'url',
           'image', // Custom rule to check remote image
       ];
   });
   

2. Post-Processing: Use afterUploaded to trigger actions (e.g., generate thumbnails):

   ->afterUploaded(fn ($record, $state) => \Image::make($state['image'])->resize(300, 200)->save())
   

3. Localization: Extend translations via config/filament-url-image-uploader.php:

   'labels' => [
       'image_url' => 'Remote Image URL',
   ],
   

4. Headless Mode: Disable the preview UI for API-only forms:

   ->previewable(false)
   ->hiddenLabel()
   ->columnSpanFull()