Intervention Image (intervention/image)

Intervention Image

https://github.com/intervention/image
Admin
Intervention Image is a PHP image processing library offering a simple interface for creating,...

Tokens:7,173
Snippets:40
Trust Score:7.9
Update:1 month ago
Show doc for...
Context Summary (auto-generated)
Raw
# Intervention Image

Intervention Image is a PHP image processing library that provides a simple and expressive way to create, edit, and compose images. It features a universal interface supporting both GD library and Imagick PHP extensions as interchangeable drivers, making it easy to switch between image manipulation backends without changing application code.

The library offers comprehensive image manipulation capabilities including resizing, cropping, rotation, color adjustments, drawing shapes, adding text, watermarking, and format encoding. It supports animated images (GIF), EXIF data handling, color profiles, and multiple output formats including JPEG, PNG, GIF, WebP, AVIF, BMP, TIFF, and HEIC. The framework-agnostic design and PSR-12 compliance make it suitable for any PHP project.

## Installation

Install the library using Composer.

```bash
composer require intervention/image
```

## Creating an ImageManager Instance

The ImageManager is the entry point for all image operations. Create an instance with either the GD or Imagick driver to handle image processing tasks.

```php
use Intervention\Image\ImageManager;
use Intervention\Image\Drivers\Gd\Driver as GdDriver;
use Intervention\Image\Drivers\Imagick\Driver as ImagickDriver;

// Create with GD driver (method 1)
$manager = new ImageManager(new GdDriver());

// Create with GD driver (static shorthand)
$manager = ImageManager::gd();

// Create with Imagick driver
$manager = ImageManager::imagick();

// Create with configuration options
$manager = ImageManager::gd(
    autoOrientation: true,    // Auto-rotate based on EXIF
    decodeAnimation: true,    // Decode animated images
    blendingColor: 'ffffff',  // Background color for transparency
    strip: false              // Strip metadata on encode
);
```

## Reading Images

Load images from various sources including file paths, binary data, base64 strings, data URIs, and file pointers.

```php
use Intervention\Image\ImageManager;

$manager = ImageManager::gd();

// Read from file path
$image = $manager->read('path/to/image.jpg');

// Read from binary data
$binaryData = file_get_contents('path/to/image.png');
$image = $manager->read($binaryData);

// Read from base64 string
$base64 = base64_encode(file_get_contents('path/to/image.gif'));
$image = $manager->read($base64);

// Read from data URI
$dataUri = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
$image = $manager->read($dataUri);

// Read from SplFileInfo
$fileInfo = new SplFileInfo('path/to/image.jpg');
$image = $manager->read($fileInfo);
```

## Creating New Images

Create blank images with specified dimensions for drawing or compositing operations.

```php
use Intervention\Image\ImageManager;

$manager = ImageManager::gd();

// Create a new blank image (800x600 pixels)
$image = $manager->create(800, 600);

// The new image has a transparent background by default
// You can fill it with a color
$image->fill('ff5500');

// Create and save immediately
$manager->create(1920, 1080)
    ->fill('000000')
    ->save('background.png');
```

## Resizing Images

Multiple resize methods are available to fit different use cases: simple resize, proportional scaling, cover, contain, and pad operations.

```php
use Intervention\Image\ImageManager;

$manager = ImageManager::gd();
$image = $manager->read('photo.jpg');

// Simple resize (may distort aspect ratio)
$image->resize(width: 400, height: 300);

// Resize with only width (height auto-calculated)
$image->resize(width: 400);

// Resize only if larger than target (resizeDown)
$image->resizeDown(width: 800, height: 600);

// Scale proportionally (maintains aspect ratio)
$image->scale(width: 400);
$image->scale(height: 300);

// Scale down only (never upscale)
$image->scaleDown(width: 1200);

// Cover: resize and crop to exact dimensions
$image->cover(400, 400, 'center');

// Cover without upscaling
$image->coverDown(800, 600, 'top');

// Contain: fit within dimensions with padding
$image->contain(800, 600, 'cccccc', 'center');

// Pad: like contain but never upscales
$image->pad(800, 600, 'ffffff', 'bottom-right');

// Save result
$image->save('resized.jpg');
```

## Cropping Images

Cut rectangular portions from images with precise positioning control.

```php
use Intervention\Image\ImageManager;

$manager = ImageManager::gd();
$image = $manager->read('landscape.jpg');

// Basic crop from top-left
$image->crop(width: 400, height: 300);

// Crop with offset from top-left corner
$image->crop(
    width: 400,
    height: 300,
    offset_x: 100,
    offset_y: 50
);

// Crop from a specific position
$image->crop(
    width: 400,
    height: 300,
    offset_x: 0,
    offset_y: 0,
    background: 'transparent',
    position: 'center'  // center, top-left, top-right, bottom-left, bottom-right, etc.
);

// Trim borders of similar color (auto-crop)
$image->trim(tolerance: 10);

// Resize canvas without resampling content
$image->resizeCanvas(1000, 800, 'ffffff', 'center');

// Add relative padding/margin
$image->resizeCanvasRelative(100, 100, 'ffffff', 'center');

$image->save('cropped.jpg');
```

## Image Effects and Filters

Apply various visual effects and color adjustments to images.

```php
use Intervention\Image\ImageManager;

$manager = ImageManager::gd();
$image = $manager->read('photo.jpg');

// Blur effect (0-100)
$image->blur(15);

// Sharpen (0-100)
$image->sharpen(20);

// Pixelate effect
$image->pixelate(10);

// Convert to greyscale
$image->greyscale();

// Invert colors
$image->invert();

// Adjust brightness (-100 to 100)
$image->brightness(25);

// Adjust contrast (-100 to 100)
$image->contrast(15);

// Gamma correction
$image->gamma(1.5);

// Colorize with RGB values (-100 to 100 each)
$image->colorize(red: 20, green: -10, blue: 0);

// Mirror horizontally (flop)
$image->flop();

// Mirror vertically (flip)
$image->flip();

// Rotate by angle (degrees, counter-clockwise)
$image->rotate(45, 'transparent');

// Auto-orient based on EXIF data
$image->orient();

// Reduce color palette
$image->reduceColors(256, 'transparent');

$image->save('filtered.jpg');
```

## Drawing Shapes

Draw geometric shapes including rectangles, circles, ellipses, lines, polygons, and bezier curves.

```php
use Intervention\Image\ImageManager;

$manager = ImageManager::gd();
$image = $manager->create(800, 600)->fill('ffffff');

// Draw a rectangle
$image->drawRectangle(100, 100, function ($rectangle) {
    $rectangle->size(200, 150);
    $rectangle->background('ff5500');
    $rectangle->border('000000', 2);
});

// Draw a circle
$image->drawCircle(500, 300, function ($circle) {
    $circle->radius(75);
    $circle->background('0066ff');
    $circle->border('003399', 3);
});

// Draw an ellipse
$image->drawEllipse(200, 400, function ($ellipse) {
    $ellipse->size(150, 100);
    $ellipse->background('00ff00');
    $ellipse->border('006600', 2);
});

// Draw a line
$image->drawLine(function ($line) {
    $line->from(50, 50);
    $line->to(750, 550);
    $line->color('ff0000');
    $line->width(3);
});

// Draw a polygon (triangle)
$image->drawPolygon(function ($polygon) {
    $polygon->point(400, 50);
    $polygon->point(300, 200);
    $polygon->point(500, 200);
    $polygon->background('ffff00');
    $polygon->border('cccc00', 2);
});

// Draw a single pixel
$image->drawPixel(400, 300, 'ff0000');

// Fill an area with flood fill
$image->fill('00ffff', 10, 10);

$image->save('shapes.png');
```

## Adding Text

Render text on images with customizable fonts, colors, alignment, and effects.

```php
use Intervention\Image\ImageManager;

$manager = ImageManager::gd();
$image = $manager->read('background.jpg');

// Basic text with callback configuration
$image->text('Hello World!', 400, 300, function ($font) {
    $font->filename('/path/to/font.ttf');  // TrueType font file
    $font->size(48);
    $font->color('ffffff');
    $font->align('center');        // left, center, right
    $font->valign('middle');       // top, middle, bottom
});

// Text with stroke/outline effect
$image->text('Outlined Text', 400, 400, function ($font) {
    $font->file('/path/to/font.ttf');
    $font->size(36);
    $font->color('ffffff');
    $font->stroke('000000', 2);    // stroke color and width
    $font->align('center');
    $font->valign('middle');
});

// Rotated text
$image->text('Rotated', 600, 200, function ($font) {
    $font->filename('/path/to/font.ttf');
    $font->size(24);
    $font->color('ff5500');
    $font->angle(45);              // rotation angle
});

// Text with line height and wrapping
$image->text('This is a long text that will be wrapped automatically', 100, 100, function ($font) {
    $font->filename('/path/to/font.ttf');
    $font->size(18);
    $font->color('333333');
    $font->lineHeight(1.5);
    $font->wrap(300);              // max width before wrapping
});

$image->save('text.png');
```

## Watermarking and Compositing

Place images, watermarks, or overlays on top of other images with positioning and opacity control.

```php
use Intervention\Image\ImageManager;

$manager = ImageManager::gd();
$image = $manager->read('photo.jpg');

// Basic watermark placement
$image->place('watermark.png');

// Place with position
$image->place(
    'logo.png',
    'bottom-right',  // position: top-left, top, top-right, left, center, right, bottom-left, bottom, bottom-right
    10,              // x offset
    10               // y offset
);

// Place with transparency
$image->place(
    'watermark.png',
    'center',
    0,
    0,
    50               // opacity (0-100)
);

// Place another image object
$watermark = $manager->read('logo.png')->resize(100, 50);
$image->place($watermark, 'top-left', 20, 20, 75);

// Multiple watermarks
$image->place('copyright.png', 'bottom-left', 10, 10, 80)
      ->place('logo.png', 'top-right', 10, 10, 90);

$image->save('watermarked.jpg');
```

## Encoding and Saving Images

Convert images to various formats with quality and format-specific options.

```php
use Intervention\Image\ImageManager;

$manager = ImageManager::gd();
$image = $manager->read('photo.png');

// Encode to JPEG with quality
$encoded = $image->toJpeg(quality: 85);
$encoded->save('output.jpg');

// Encode to JPEG with options
$encoded = $image->toJpeg(
    quality: 90,
    progressive: true,   // progressive JPEG
    strip: true          // strip metadata
);

// Encode to PNG
$encoded = $image->toPng(
    interlaced: true,    // interlaced PNG
    indexed: false       // indexed color mode
);
$encoded->save('output.png');

// Encode to WebP
$encoded = $image->toWebp(quality: 80);
$encoded->save('output.webp');

// Encode to GIF (supports animation)
$encoded = $image->toGif();
$encoded->save('output.gif');

// Encode to AVIF (modern format)
$encoded = $image->toAvif(quality: 75);
$encoded->save('output.avif');

// Encode to BMP
$encoded = $image->toBitmap();
$encoded->save('output.bmp');

// Encode by file extension
$encoded = $image->encodeByExtension('webp', quality: 85);

// Encode by media type
$encoded = $image->encodeByMediaType('image/jpeg', quality: 90);

// Encode by file path (auto-detect format)
$encoded = $image->encodeByPath('output.png');

// Direct save (encodes based on extension)
$image->save('output.jpg', quality: 85);

// Get encoded data as string
$data = $encoded->toString();

// Get as data URI
$dataUri = $encoded->toDataUri();
// Returns: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...

// Get media type
$mediaType = $encoded->mediaType();  // e.g., "image/jpeg"

// Get file size
$size = $encoded->size();  // bytes
```

## Working with Image Information

Retrieve metadata and color information from images.

```php
use Intervention\Image\ImageManager;

$manager = ImageManager::gd();
$image = $manager->read('photo.jpg');

// Get dimensions
$width = $image->width();      // e.g., 1920
$height = $image->height();    // e.g., 1080
$size = $image->size();        // Rectangle object

// Get resolution (DPI)
$resolution = $image->resolution();
$xDpi = $resolution->x();
$yDpi = $resolution->y();

// Set resolution
$image->setResolution(300, 300);

// Get colorspace
$colorspace = $image->colorspace();

// Get EXIF data
$exif = $image->exif();                    // all EXIF data as Collection
$camera = $image->exif('IFD0.Model');      // specific EXIF field

// Pick color at coordinates
$color = $image->pickColor(100, 50);       // at x=100, y=50
$red = $color->red()->value();             // 0-255
$green = $color->green()->value();         // 0-255
$blue = $color->blue()->value();           // 0-255
$alpha = $color->alpha()->value();         // 0-255

// Get hex color
$hex = $color->toHex();           // e.g., "ff5500"
$hex = $color->toHex('#');        // e.g., "#ff5500"

// Get color string
$string = $color->toString();     // e.g., "rgb(255, 85, 0)" or "rgba(255, 85, 0, 0.5)"

// Check if animated
$isAnimated = $image->isAnimated();

// Get frame count
$frameCount = $image->count();
```

## Working with Animated Images

Handle animated GIFs and other multi-frame images.

```php
use Intervention\Image\ImageManager;

$manager = ImageManager::gd();

// Read animated GIF
$image = $manager->read('animated.gif');

// Check if animated
if ($image->isAnimated()) {
    echo "Frame count: " . $image->count();
}

// Get/set loop count (0 = infinite)
$loops = $image->loops();
$image->setLoops(3);  // play 3 times

// Remove animation (keep single frame)
$image->removeAnimation(0);           // keep first frame
$image->removeAnimation('50%');       // keep middle frame

// Slice animation frames
$image->sliceAnimation(offset: 0, length: 10);  // keep first 10 frames

// Create animated image from scratch
$animated = $manager->animate(function ($animation) {
    // Add frames with delay (in 1/100 seconds)
    $animation->add('frame1.png', 0.1);
    $animation->add('frame2.png', 0.1);
    $animation->add('frame3.png', 0.1);
});

// Iterate over frames
foreach ($image as $frame) {
    // Process each frame
    $delay = $frame->delay();  // frame delay
}

// Save animated image
$image->toGif()->save('output.gif');
```

## Color Handling

Work with colors using various formats including hex, RGB, RGBA, and named colors.

```php
use Intervention\Image\ImageManager;
use Intervention\Image\Colors\Rgb\Color;

$manager = ImageManager::gd();
$image = $manager->create(400, 400);

// Fill with hex color
$image->fill('ff5500');
$image->fill('#ff5500');
$image->fill('f50');        // shorthand

// Fill with RGB
$image->fill('rgb(255, 85, 0)');

// Fill with RGBA (with transparency)
$image->fill('rgba(255, 85, 0, 0.5)');

// Fill with named color
$image->fill('orange');
$image->fill('transparent');

// Create color object directly
$color = new Color(255, 85, 0, 255);  // RGBA values (0-255)
$color = new Color(255, 85, 0);       // RGB (alpha defaults to 255)

// Color methods
$isTransparent = $color->isTransparent();
$isGreyscale = $color->isGreyscale();
$isClear = $color->isClear();         // fully transparent

// Draw with colors
$image->drawRectangle(50, 50, function ($rect) {
    $rect->size(100, 100);
    $rect->background('rgba(255, 0, 0, 0.5)');
    $rect->border('#000000', 2);
});

// Blend transparency with background color
$image->blendTransparency('ffffff');  // replace transparency with white

// Set blending color for format conversion
$image->setBlendingColor('000000');
$image->toJpeg()->save('output.jpg');  // transparent areas become black

$image->save('colors.png');
```

## Color Profiles

Manage ICC color profiles for color-accurate image processing.

```php
use Intervention\Image\ImageManager;
use Intervention\Image\Colors\Profile;

$manager = ImageManager::imagick();  // Imagick has better profile support
$image = $manager->read('photo.jpg');

// Get current profile
try {
    $profile = $image->profile();
} catch (\Exception $e) {
    // Image has no embedded profile
}

// Load and set ICC profile
$srgbProfile = Profile::fromPath('/path/to/sRGB.icc');
$image->setProfile($srgbProfile);

// Remove profile
$image->removeProfile();

// Get/set colorspace
$colorspace = $image->colorspace();
$image->setColorspace('rgb');
$image->setColorspace('cmyk');

$image->save('profiled.jpg');
```

## Summary

Intervention Image excels at common web application tasks such as generating thumbnails, processing user uploads, adding watermarks, creating social media images, and converting between formats. The fluent interface allows chaining multiple operations, making it easy to resize, apply effects, add watermarks, and encode in a single expression. Integration with Laravel and other frameworks is straightforward through service providers and facades.

The library's driver abstraction means you can start with GD (available on most PHP installations) and switch to Imagick for advanced features like better quality scaling, CMYK support, or additional format support without changing application code. For production environments, consider the memory implications of image processing and implement appropriate queuing for batch operations. The encoded image objects provide flexible output options including direct file saving, string conversion for storage backends, and data URIs for inline embedding.