Imagine Vips Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require rokka/imagine-vips
   

   Ensure either:

   • PHP FFI extension (recommended) OR
   • php-vips-ext ≥1.0.8 (manual install) AND
   • php-vips (auto-installed via Composer).

2. Verify libvips:

   use Imagine\Vips\Imagine;
   
   $imagine = new Imagine();
   if ($imagine->isSupported()) {
       echo "libvips is ready!";
   }
   

First Use Case: Thumbnail Generation

$imagine = new Imagine();
$image = $imagine->open('large-image.jpg')
    ->thumbnail(new \Imagine\Image\Box(200, 200))
    ->save('thumbnail.jpg');

Implementation Patterns

Core Workflows

1. Image Manipulation:

   $image = $imagine->open('input.jpg')
       ->resize(new \Imagine\Image\Box(800, 600))
       ->rotate(90) // Only 90° increments work with libvips <8.6
       ->crop(new \Imagine\Image\Box(400, 300), new \Imagine\Image\Point(100, 100))
       ->save('output.jpg');
   

2. Layer/Animation Support (vips ≥8.7):

   $layers = $imagine->open('animated.gif')->layers();
   $layers->setDelay(0, 500); // Set delay for frame 0 to 500ms
   $layers->save('output.gif');
   

3. Format-Specific Options:

   $image->save('output.webp', [
       'webp_reduction_effort' => 6, // Max quality (0-6)
       'quality' => 90,
   ]);
   

Integration Tips

• Fallback Handling: Use convertToAlternative() for unsupported operations:

  $image->convertToAlternative(new \Imagine\Gd\Imagine())->save('fallback.jpg');
  

• Performance: Leverage libvips’ low-memory design for large files (e.g., 100MB+).
• Metadata: Strip profiles with:

  $image->stripProfiles()->save('clean.jpg');
  

Gotchas and Tips

Pitfalls

1. Version Dependencies:

   • libvips ≥8.6 required for paste() and arbitrary-angle rotation.
   • libvips ≥8.7 for animated GIFs/WebP and magicksave (fallback to Imagick/GD if missing).
   • PHP FFI preferred over php-vips-ext (better performance/maintenance).

2. BC Breaks:

   • 0.41.0: autorotate/n defaults now apply during open().
   • 0.40.0: Drawer::text() behavior changed (use textWithHeight() for legacy).
   • 0.30.0: Extending \Imagine\Vips\Layers requires explicit return types.

3. Unsupported Features:

   • Filters: fill(), histogram, colorize missing (fallback to Imagick/GD).
   • Drawers: Only text supported (contribute to extend!).

Debugging

• Check libvips Version:

  echo \Jcupitt\Vips\Config::version(); // e.g., "8.12.2"
  

• Enable Warnings: Set vips_cache_set_max_mem in constructor:

  $imagine = new Imagine(['vips_cache_set_max_mem' => 1024 * 1024 * 1024]); // 1GB
  

• Fallback Gracefully:

  try {
      $image->save('output.heic');
  } catch (\Imagine\Exception\NotSupportedException $e) {
      $image->convertToAlternative()->save('output.jpg');
  }
  

Extension Points

1. Custom Save Options:

   $image->save('output.jpg', [
       'jp2_quality' => 95, // JPEG2000 (if supported)
       'force_magick' => true, // Force magicksave (vips ≥8.7)
   ]);
   

2. Override Defaults:

   $imagine = new Imagine([
       'default_options' => [
           'quality' => 85,
           'png_quality' => 100, // Disable pngquant
       ],
   ]);
   

3. Contribute Missing Features:
   • Drawer: Extend \Imagine\Vips\Drawer for shapes/colors.
   • Filters: Implement fill()/histogram in \Imagine\Vips\Image.