Image Asset Laravel Package

Getting Started

Minimal Setup

1. Installation Run composer require camelot/image-asset in your Laravel project. No additional bundle registration is required (unlike Symfony) since Laravel doesn’t use bundles.

2. Publish Config Publish the default config with:

   php artisan vendor:publish --provider="Camelot\ImageAsset\ServiceProvider"
   

   This creates config/camelot_image_asset.php.

3. First Use Case: Generate a Thumbnail Use the ImageAsset facade or service directly:

   use Camelot\ImageAsset\Facades\ImageAsset;
   
   // Generate a 200x200 thumbnail of an image
   $thumbnail = ImageAsset::createThumbnail('path/to/image.jpg', 200, 200);
   

Implementation Patterns

Core Workflows

1. Dynamic Thumbnail Generation Use the ImageAsset service to generate thumbnails on-the-fly:

   // In a controller or service
   $imagePath = ImageAsset::generateThumbnail(
       'public/images/original.jpg',
       300, 300,
       ['action' => 'resize', 'quality' => 80]
   );
   

   • Actions: resize, crop, watermark, etc. (check config for available actions).

2. URL-Based Access Configure routes to serve thumbnails dynamically (e.g., /thumbs/200x200/resize/image.jpg). Update Laravel’s routes/web.php:

   Route::get('/thumbs/{width}x{height}/{action}/{file}', [
       'uses' => [\Camelot\ImageAsset\Controller\ImageController::class, 'serve'],
       'as' => 'camelot.image'
   ]);
   

3. Batch Processing Use the ImageAsset service to process multiple images:

   $files = ['image1.jpg', 'image2.png'];
   foreach ($files as $file) {
       ImageAsset::generateThumbnail($file, 200, 200);
   }
   

Integration Tips

• Storage Integration: Override static_path in config to use Laravel’s storage/app/public:

  'static_path' => storage_path('app/public/thumbs'),
  

  Run php artisan storage:link afterward.

• Caching: Enable caching in config to avoid reprocessing:

  'cache' => [
      'enabled' => true,
      'ttl' => 86400, // 1 day in seconds
  ],
  

• Custom Actions: Extend the package by adding new actions in a service provider:

  public function register()
  {
      $this->app->extend('camelot.image_asset.actions', function ($actions) {
          $actions['custom_action'] = function ($image, $params) {
              // Custom logic
          };
          return $actions;
      });
  }
  

Gotchas and Tips

Common Pitfalls

1. GD Library Missing Ensure php-gd is installed (sudo apt-get install php-gd or equivalent). Test with php -m | grep gd in the terminal.

2. File Permissions Thumbnails are saved to static_path. Ensure the directory is writable:

   chmod -R 755 storage/app/public/thumbs
   

3. Route Conflicts Avoid naming conflicts with existing routes. Use unique mount points:

   'routing' => [
       'mount_point' => '/custom-thumbs',
   ],
   

4. Caching Issues Clear cached thumbnails manually if needed:

   php artisan cache:clear
   rm -rf storage/framework/cache/*
   

Debugging Tips

• Log Actions: Enable debug mode in config:

  'debug' => true,
  

  Logs will appear in storage/logs/laravel.log.

• Check Generated Paths: Use dd() to inspect paths:

  $path = ImageAsset::getThumbnailPath('image.jpg', 200, 200);
  dd($path);
  

Extension Points

1. Custom Actions Add new actions by binding them in a service provider (see Integration Tips).

2. Override Controllers Replace the default ImageController by binding a new controller:

   $this->app->bind(
       \Camelot\ImageAsset\Controller\ImageController::class,
       \App\Http\Controllers\CustomImageController::class
   );
   

3. Modify Config Dynamically Use Laravel’s config binding to override settings per environment:

   config(['camelot_image_asset.static_path' => env('CUSTOM_THUMB_PATH')]);