Filament Take Picture Field Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require emmanpbarrameda/filament-take-picture-field
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Emmanpbarrameda\FilamentTakePictureField\FilamentTakePictureFieldServiceProvider" --tag="filament-take-picture-field-config"
   

2. First Use Case: Add the field to a Filament form resource:

   use Emmanpbarrameda\FilamentTakePictureField\Fields\TakePictureField;
   
   TakePictureField::make('profile_photo')
       ->label('Profile Photo')
       ->required()
       ->directory('profile-photos')
       ->visibility('public')
       ->aspectRatio(1) // 1:1 ratio
       ->maxDimensions(1024, 1024),
   

3. Where to Look First:

   • README.md for feature highlights.
   • Config file for default settings.
   • Example usage in the README for quick integration.

Implementation Patterns

Common Workflows

1. Basic Integration: Use the field in a Filament resource form:

   TakePictureField::make('product_image')
       ->directory('products')
       ->visibility('private')
       ->maxDimensions(2048, 2048),
   

2. Multi-Camera Support: Enable camera selection for devices with multiple cameras:

   TakePictureField::make('document_scan')
       ->allowCameraSelection()
       ->directory('documents'),
   

3. Multiple Shots: Capture multiple images in a single field:

   TakePictureField::make('gallery_images')
       ->multiple()
       ->maxShots(5)
       ->directory('gallery'),
   

4. Dynamic Configuration: Use closures for dynamic settings:

   TakePictureField::make('dynamic_photo')
       ->directory(fn ($record) => "users/{$record->id}/photos")
       ->maxDimensions(fn () => [config('app.max_width'), config('app.max_height')]),
   

5. Validation and Processing: Combine with Filament’s validation rules:

   TakePictureField::make('avatar')
       ->required()
       ->image()
       ->maxSize(2048)
       ->directory('avatars'),
   

6. Displaying Captured Images: Use the field in a table for display:

   use Emmanpbarrameda\FilamentTakePictureField\Columns\TakePictureColumn;
   
   TakePictureColumn::make('profile_photo')
       ->width(64)
       ->height(64),
   

Integration Tips

• Storage: Ensure the specified directory exists in your filesystem (e.g., storage/app/public/profile-photos).
• Permissions: Set proper permissions for the directory if using visibility('public').
• Frontend Dependencies: The package relies on modern browser APIs (e.g., MediaDevices). Test in supported browsers.
• Fallback: Provide a fallback file upload option for unsupported devices:

  TakePictureField::make('fallback_image')
      ->fallbackUpload()
      ->directory('fallbacks'),
  

Gotchas and Tips

Pitfalls

1. Browser Compatibility:

   • The camera API may not work in older browsers (e.g., IE, Safari <13). Test thoroughly.
   • Mobile browsers (e.g., Safari on iOS) may require user interaction (e.g., a button click) to trigger the camera.

2. Directory Permissions:

   • If using visibility('public'), ensure the directory is symlinked to public/storage:

     php artisan storage:link
     

   • Private directories must be writable by the web server user (e.g., www-data or nginx).

3. Image Processing:

   • The package resizes images to maxDimensions, but heavy resizing may impact performance. Test with large images.
   • Custom processing (e.g., cropping) requires extending the field (see below).

4. Multiple Shots:

   • Storing multiple images in a single field may bloat your database. Consider using a separate table or JSON column for metadata.

5. CORS Issues:

   • If serving the Filament admin panel from a subdomain, ensure CORS is configured for the camera API:

     // config/cors.php
     'paths' => ['api/*', 'sanctum/csrf-cookie', 'filament/*'],
     

Debugging

1. Camera Not Working:

   • Check browser console for errors (e.g., NotAllowedError for permission issues).
   • Ensure HTTPS is used (camera API requires secure contexts).

2. Images Not Saving:

   • Verify the directory path is correct and writable.
   • Check Laravel logs (storage/logs/laravel.log) for filesystem errors.

3. Field Not Rendering:

   • Ensure the package is registered in config/filament.php under form_components.
   • Clear Filament’s view cache:

     php artisan filament:cache:clear
     

Tips

1. Extending the Field: Customize behavior by extending the field:

   namespace App\Filament\Fields;
   
   use Emmanpbarrameda\FilamentTakePictureField\Fields\TakePictureField;
   
   class CustomTakePictureField extends TakePictureField
   {
       protected function setUp(): void
       {
           parent::setUp();
   
           $this->beforeSaving(function ($record, $state) {
               // Add custom logic (e.g., rename files, add watermarks)
               $state['custom_processed'] = true;
           });
       }
   }
   

2. Dynamic Directories: Use closures for dynamic directories based on record attributes:

   TakePictureField::make('user_photo')
       ->directory(fn ($record) => "users/{$record->id}/photos_{$record->created_at->format('Y-m')}")
       ->visibility('private'),
   

3. Fallback for Unsupported Devices: Combine with a regular file upload field:

   Column::make('photo')
       ->image()
       ->fallback(
           FileUpload::make('photo_fallback')
               ->directory('fallbacks')
               ->image()
       ),
   

4. Testing: Mock the camera API in tests using tools like jsdom or Puppeteer:

   // Example using Pest and BrowserKit
   $response = $this->get('/filament/resources/test-resource/create');
   $response->assertSee('Camera access required');
   

5. Performance:

   • For large-scale use, consider lazy-loading images or using a CDN for public images.
   • Optimize image quality with quality():

     TakePictureField::make('thumbnail')
         ->quality(80)
         ->maxDimensions(512, 512),
     

6. Localization: Customize labels and messages in your language files:

   // lang/en/filament-take-picture-field.php
   return [
       'camera_access_required' => 'Please allow camera access to capture your photo.',
   ];