Magickit Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require supernova3339/magickit
   php artisan ui magickit
   npm install && npm run dev
   

   • Run php artisan magickit:install if the package provides a dedicated installer command (verify via php artisan).
   • Ensure MAGICKIT_ENABLED=true is set in .env to activate the package.

2. First Use Case:

   • Image Uploads: Use the Magickit facade to process images on-the-fly:

     use Supernova3339\Magickit\Facades\Magickit;
     
     $path = Magickit::upload('path/to/image.jpg')
         ->resize(800, 600)
         ->watermark('watermark.png')
         ->save('public/uploads/processed.jpg');
     

   • Middleware: Leverage the MagickitMiddleware for automatic processing of uploaded files via app/Http/Kernel.php:

     'web' => [
         \Supernova3339\Magickit\Http\Middleware\MagickitMiddleware::class,
         // ...
     ],
     

3. Where to Look First:

   • Config: config/magickit.php for default settings (e.g., storage paths, allowed formats, watermarks).
   • Service Provider: Supernova3339\Magickit\MagickitServiceProvider for booting events and bindings.
   • Facade API: Supernova3339\Magickit\Facades\Magickit for chainable methods (e.g., resize(), compress(), applyFilters()).

Implementation Patterns

Core Workflows

1. File Processing Pipeline:

   • Chain methods for multi-step transformations:

     Magickit::from('input.jpg')
         ->resize(1200, null, 'crop') // Auto-height, crop if needed
         ->sharpen(10)
         ->applyFilters(['grayscale', 'sepia'])
         ->save('output.jpg');
     

   • Batch Processing:

     $files = ['file1.jpg', 'file2.png'];
     foreach ($files as $file) {
         Magickit::from($file)->resize(400, 400)->save("thumbs/{$file}");
     }
     

2. Middleware Integration:

   • Automatically process files uploaded via forms:

     // In a controller
     public function store(Request $request) {
         $request->validate(['image' => 'required|image']);
         $path = $request->file('image')->store('uploads');
         // Processed path is available in $request->magickit_path
     }
     

   • Configure middleware in app/Http/Kernel.php to exclude routes (e.g., API endpoints):

     'api' => [
         // Exclude MagickitMiddleware for API routes
     ],
     

3. Storage Integration:

   • Use with Laravel’s filesystem:

     use Storage;
     
     $url = Magickit::from(Storage::path('raw/image.jpg'))
         ->resize(800, 600)
         ->saveAs('processed', 'public')
         ->getUrl();
     

4. Event Listeners:

   • Trigger actions post-processing (e.g., update database records):

     // In EventServiceProvider
     protected $listen = [
         \Supernova3339\Magickit\Events\ImageProcessed::class => [
             \App\Listeners\UpdateProductGallery::class,
         ],
     ];
     

Integration Tips

• Validation: Extend Laravel’s validation rules to enforce Magickit constraints:

  use Supernova3339\Magickit\Rules\MagickitRule;
  
  $request->validate([
      'image' => ['required', 'image', new MagickitRule(['resize' => [1024, 768]])],
  ]);
  

• Queue Jobs: Offload heavy processing to queues:

  dispatch(new ProcessImageJob($request->file('image'), 'thumbs'));
  

• Blade Directives: Create custom Blade components for dynamic image tags:

  @magickit('image.jpg', ['resize' => [200, 200], 'watermark' => true])
  

Gotchas and Tips

Pitfalls

1. Imagick Extension:

   • Error: Class 'Imagick' not found or failed to apply font: 'dejavu'.
   • Fix: Ensure PHP’s imagick extension is installed and enabled:

     pecl install imagick
     sudo nano /etc/php/{version}/cli/php.ini  # Add `extension=imagick.so`
     sudo nano /etc/php/{version}/fpm/php.ini  # For FPM
     sudo systemctl restart php{version}-fpm
     

   • Fallback: Use gd library (slower) by setting MAGICKIT_DRIVER=gd in .env.

2. File Permissions:

   • Error: Permission denied when saving files.
   • Fix: Ensure the storage directory is writable:

     chmod -R 775 storage/app/public
     chown -R www-data:www-data storage/app/public  # Adjust user as needed
     

3. Memory Limits:

   • Error: Out of memory for large images.
   • Fix: Increase PHP memory limit in .env:

     MAGICKIT_MEMORY_LIMIT=512M
     

   • Tip: Use ->compress(80) to reduce file size before processing.

4. Watermark Paths:

   • Error: Watermark not found.
   • Fix: Verify watermarks.path in config/magickit.php points to the correct directory and files exist.

5. Middleware Conflicts:

   • Error: Call to undefined method when using magickit_path in requests.
   • Fix: Ensure MagickitMiddleware is registered after ConvertEmptyStringsToNullMiddleware in Kernel.php.

Debugging

• Log Processing: Enable debug mode in .env:

  MAGICKIT_DEBUG=true
  

  Check storage/logs/laravel.log for detailed processing steps.

• Test Locally: Use php artisan magickit:test (if available) or manually test with:

  Magickit::from('test.jpg')->debug()->resize(100, 100)->save('debug.jpg');
  

Config Quirks

• Default Values: Override defaults in .env:

  MAGICKIT_DEFAULT_WIDTH=1200
  MAGICKIT_DEFAULT_QUALITY=85
  MAGICKIT_ALLOWED_FORMATS=jpg,png,gif,webp
  

• Dynamic Config: Use config(['magickit.key' => value]) to modify settings at runtime.

Extension Points

1. Custom Filters: Add new filters by publishing the config:

   php artisan vendor:publish --provider="Supernova3339\Magickit\MagickitServiceProvider" --tag="config"
   

   Extend config/magickit.php:

   'filters' => [
       'custom' => [
           'command' => 'modulate 100,100,100', // Darken image
           'description' => 'Apply custom dark effect',
       ],
   ],
   

   Use in code:

   Magickit::from('image.jpg')->applyFilters(['custom'])->save('output.jpg');
   

2. Events: Listen for ImageProcessed events to extend functionality:

   // In a listener
   public function handle(ImageProcessed $event) {
       // Example: Log processed files or update analytics
       Log::info('Processed ' . $event->path);
   }
   

3. Service Provider Binding: Bind custom classes to the container for advanced use:

   $this->app->bind('magickit.custom', function () {
       return new CustomMagickitProcessor();
   });