Gif Creator Laravel Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require plutuss/gif-creator-laravel
   

   For Laravel < 5.5, register the service provider and facade in config/app.php.

2. First Use Case: Convert an array of images into a GIF and display it in a browser:

   use Plutuss\Gif\Facades\GifCreator;
   
   $gif = GifCreator::storage('public')
       ->frames(['frame1.png', 'frame2.png'], 'path/to/images/')
       ->durations([500, 500]) // Durations in milliseconds
       ->makeGif();
   
   return $gif->show(); // Directly output the GIF in a view
   

3. Where to Look First:

   • Facade: GifCreator for fluent method chaining.
   • Storage: Use storage('disk-name') to specify where frames are read from (e.g., public, s3).
   • README Methods: Focus on frames(), durations(), and makeGif() for basic workflows.

Implementation Patterns

Core Workflows

1. Dynamic GIF Generation from User Uploads:

   $request->validate(['images' => 'required|array']);
   $files = $request->file('images');
   
   $gif = GifCreator::storage('public')
       ->frames(array_map(fn($file) => $file->hashName(), $files), storage_path('app/public'))
       ->durations(array_fill(0, count($files), 300)) // 300ms per frame
       ->loop(0) // Infinite loop
       ->makeGif();
   
   return $gif->save('user-gifs/', 'user-'.auth()->id().'.gif');
   

2. Background Processing with Queues: Use Laravel Queues to offload GIF creation:

   // Dispatch a job
   CreateGifJob::dispatch($imagePaths, $durations, $outputPath);
   
   // Job class
   public function handle() {
       $gif = GifCreator::storage('public')
           ->frames($this->imagePaths, storage_path('app/public'))
           ->durations($this->durations)
           ->makeGif();
   
       Storage::disk('public')->put($this->outputPath, $gif->getGif());
   }
   

3. Reusing GIF Data: Cache generated GIFs to avoid reprocessing:

   $cacheKey = "gif_{$request->input('config_hash')}";
   
   if (Cache::has($cacheKey)) {
       return response()->make(Cache::get($cacheKey), 200, ['Content-Type' => 'image/gif']);
   }
   
   $gif = GifCreator::storage('public')
       ->frames($frames)
       ->durations($durations)
       ->makeGif();
   
   Cache::put($cacheKey, $gif->getGif(), now()->addHours(1));
   return $gif->show();
   

Integration Tips

• Validation: Validate frame paths/durations before processing:

  $this->validateFrames($frames, $path);
  $this->validateDurations($durations, count($frames));
  

• Error Handling: Wrap makeGif() in try-catch to handle missing files or corrupt images.
• Storage Disks: Leverage Laravel’s filesystem config for flexibility (e.g., S3, local disks).

Gotchas and Tips

Pitfalls

1. Frame Path Resolution:

   • Issue: frames() expects paths relative to the disk’s root (e.g., storage/app/public for public disk).
   • Fix: Use absolute paths or prepend storage_path():

     $frames = array_map(fn($file) => "public/{$file}", $request->input('frames'));
     

2. Memory Limits:

   • Issue: Large GIFs (e.g., 100+ frames) may hit PHP’s memory_limit.
   • Fix: Increase memory_limit in .env or process frames in batches.

3. Disk Permissions:

   • Issue: Storage::put() fails silently if the disk lacks write permissions.
   • Fix: Verify disk permissions:

     if (!Storage::disk('public')->exists('gif/')) {
         Storage::disk('public')->makeDirectory('gif/');
     }
     

4. Facade Not Registered:

   • Issue: GifCreator throws ClassNotFound if the service provider isn’t registered (Laravel < 5.5).
   • Fix: Manually add the provider/alias to config/app.php.

Debugging

• Log Frame Paths:

  \Log::debug('Frame paths:', ['paths' => $frames, 'disk' => $disk]);
  

• Check GIF Data: Use dd($gif->getGif()) to verify binary output before saving.

Extension Points

1. Custom Frame Sources: Extend the facade to support dynamic frame generation (e.g., Canvas API):

   // Hypothetical extension
   GifCreator::canvasFrames(function() {
       return collect(range(1, 10))->map(fn($i) => Canvas::drawFrame($i));
   });
   

2. Post-Processing: Chain additional methods after makeGif():

   $gif->optimize(); // Hypothetical method to reduce file size
   

3. Event Listeners: Trigger events for GIF creation/saving:

   event(new GifCreated($gif, $outputPath));
   

Config Quirks

• Default Disk: The package defaults to local disk if none is specified. Explicitly set it for clarity:

  GifCreator::storage('public')->frames(...);
  

• Duration Units: Durations are in milliseconds (not seconds). Adjust expectations accordingly.