Skip to content

Image Processing Guide

Image Processing Guide

Cbox images include three powerful image processing libraries plus Browsershot support for PDF generation.

Quick Start

// GD - Simple operations
$img = imagecreatefrompng('input.png');
imagejpeg($img, 'output.jpg', 90);

// ImageMagick - Advanced operations
$im = new Imagick('input.heic');
$im->setImageFormat('jpeg');
$im->writeImage('output.jpg');

Library Comparison

Feature GD ImageMagick
Memory usage Medium High
Speed Medium Medium
HEIC/HEIF - ✓
PDF read/write - ✓
SVG support - ✓
Color profiles - ✓
Laravel Integration intervention/image intervention/image

Recommendation:

  • GD: Simple thumbnails, basic operations
  • ImageMagick: Complex manipulations, format conversions, PDF

GD Library

Best for simple operations with good Laravel/Intervention support.

Basic Operations

// Create thumbnail
$src = imagecreatefromjpeg('photo.jpg');
$thumb = imagescale($src, 300, 200);
imagejpeg($thumb, 'thumbnail.jpg', 85);
imagedestroy($src);
imagedestroy($thumb);

// Convert formats
$png = imagecreatefrompng('input.png');
imagewebp($png, 'output.webp', 80);
imagedestroy($png);

// Add watermark
$photo = imagecreatefromjpeg('photo.jpg');
$watermark = imagecreatefrompng('watermark.png');
imagecopy($photo, $watermark, 10, 10, 0, 0, imagesx($watermark), imagesy($watermark));
imagejpeg($photo, 'watermarked.jpg');

Check GD Capabilities

$info = gd_info();
echo "GD Version: " . $info['GD Version'] . "\n";
echo "JPEG: " . ($info['JPEG Support'] ? 'Yes' : 'No') . "\n";
echo "PNG: " . ($info['PNG Support'] ? 'Yes' : 'No') . "\n";
echo "WebP: " . ($info['WebP Support'] ? 'Yes' : 'No') . "\n";
echo "AVIF: " . ($info['AVIF Support'] ? 'Yes' : 'No') . "\n";

ImageMagick (Imagick)

Best for complex operations, format conversions, and PDF handling.

Basic Operations

// Resize with aspect ratio
$im = new Imagick('photo.jpg');
$im->thumbnailImage(800, 0); // Width 800, auto height
$im->writeImage('resized.jpg');

// Convert to WebP
$im = new Imagick('photo.jpg');
$im->setImageFormat('webp');
$im->setImageCompressionQuality(80);
$im->writeImage('output.webp');

// Strip metadata (privacy)
$im = new Imagick('photo.jpg');
$im->stripImage();
$im->writeImage('stripped.jpg');

HEIC/HEIF Conversion (iPhone Photos)

// Convert iPhone HEIC to JPEG
$im = new Imagick('IMG_1234.HEIC');
$im->setImageFormat('jpeg');
$im->setImageCompressionQuality(90);
$im->writeImage('photo.jpg');

// Batch convert all HEIC files
foreach (glob('*.HEIC') as $heic) {
    $im = new Imagick($heic);
    $im->setImageFormat('jpeg');
    $im->writeImage(str_replace('.HEIC', '.jpg', $heic));
    $im->clear();
}

PDF Operations

// Generate PDF from image
$im = new Imagick('document.jpg');
$im->setImageFormat('pdf');
$im->writeImage('document.pdf');

// Read PDF page as image
$im = new Imagick();
$im->setResolution(150, 150); // Set BEFORE reading
$im->readImage('document.pdf[0]'); // First page
$im->setImageFormat('png');
$im->writeImage('page1.png');

// Multi-page PDF to images
$im = new Imagick();
$im->setResolution(150, 150);
$im->readImage('document.pdf');
foreach ($im as $i => $page) {
    $page->setImageFormat('png');
    $page->writeImage("page_{$i}.png");
}

SVG Rendering

// SVG to PNG (read-only for security)
$im = new Imagick();
$im->setBackgroundColor(new ImagickPixel('transparent'));
$im->readImage('icon.svg');
$im->setImageFormat('png');
$im->writeImage('icon.png');

// SVG at specific size
$im = new Imagick();
$im->setResolution(300, 300);
$im->readImage('icon.svg');
$im->resizeImage(512, 512, Imagick::FILTER_LANCZOS, 1);
$im->writeImage('icon-512.png');

Check ImageMagick Capabilities

// List supported formats
$formats = Imagick::queryFormats();
echo "Supported formats: " . count($formats) . "\n";

// Check specific format
$hasHeic = in_array('HEIC', $formats);
$hasPdf = in_array('PDF', $formats);
$hasSvg = in_array('SVG', $formats);

echo "HEIC: " . ($hasHeic ? 'Yes' : 'No') . "\n";
echo "PDF: " . ($hasPdf ? 'Yes' : 'No') . "\n";
echo "SVG: " . ($hasSvg ? 'Yes' : 'No') . "\n";

libvips (removed)

The vips PHP extension is no longer in these images.

It was the one extension with no PIE package under any name: PECL-only, with an upstream repository untouched since October 2024 whose newest git tag is three releases behind what PECL serves. pecl itself is gone from PHP 8.6 images and the PECL service has a stated shelf life, so vips could not survive that transition by waiting, by migrating, or by building from a tag.

If you used it: intervention/image runs on either GD or ImageMagick and is the usual replacement, and ImageMagick covers the formats the table above gives libvips (HEIC/HEIF, SVG, colour profiles). What you lose is libvips' memory profile on very large images - if that is load-bearing for you, run libvips as its own service rather than in the PHP container.


Browsershot (PDF Generation)

The Chromium and Dev tiers include Chromium for Browsershot PDF/screenshot generation. Use the -chromium or -dev tag suffix.

Installation

composer require spatie/browsershot

Generate PDF from HTML

use Spatie\Browsershot\Browsershot;

// Simple PDF
Browsershot::html('<h1>Hello World</h1>')
    ->save('document.pdf');

// From URL
Browsershot::url('https://example.com')
    ->save('page.pdf');

// With options
Browsershot::html($html)
    ->format('A4')
    ->margins(20, 20, 20, 20)
    ->showBackground()
    ->save('styled.pdf');

Generate Screenshots

use Spatie\Browsershot\Browsershot;

// Full page screenshot
Browsershot::url('https://example.com')
    ->fullPage()
    ->save('screenshot.png');

// Specific viewport
Browsershot::url('https://example.com')
    ->windowSize(1920, 1080)
    ->save('desktop.png');

// Mobile viewport
Browsershot::url('https://example.com')
    ->windowSize(375, 812)
    ->device('iPhone X')
    ->save('mobile.png');

Browsershot Configuration

Cbox sets these environment variables automatically:

PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

If needed manually:

Browsershot::html($html)
    ->setChromePath('/usr/bin/chromium-browser')
    ->noSandbox()
    ->save('output.pdf');

Laravel Integration

Intervention Image (GD/ImageMagick)

composer require intervention/image
use Intervention\Image\ImageManager;
use Intervention\Image\Drivers\Gd\Driver as GdDriver;
use Intervention\Image\Drivers\Imagick\Driver as ImagickDriver;

// Using GD
$manager = new ImageManager(new GdDriver());
$image = $manager->read('photo.jpg');
$image->scale(width: 300);
$image->save('thumbnail.jpg');

// Using ImageMagick (for HEIC, PDF, etc.)
$manager = new ImageManager(new ImagickDriver());
$image = $manager->read('photo.HEIC');
$image->toJpeg(90)->save('photo.jpg');

Spatie Media Library

composer require spatie/laravel-medialibrary
// Model setup
class Post extends Model implements HasMedia
{
    use InteractsWithMedia;

    public function registerMediaConversions(Media $media = null): void
    {
        $this->addMediaConversion('thumb')
            ->width(300)
            ->height(200);

        $this->addMediaConversion('webp')
            ->format('webp')
            ->quality(80);
    }
}

// Usage
$post->addMedia($request->file('image'))->toMediaCollection();

Common Tasks

Optimize Images for Web

// ImageMagick optimization
$im = new Imagick('photo.jpg');
$im->setImageCompressionQuality(85);
$im->stripImage();  // Remove metadata
$im->gaussianBlurImage(0.05, 0.5);  // Slight blur helps compression
$im->writeImage('optimized.jpg');

// Convert to modern formats
$im->setImageFormat('webp');
$im->writeImage('photo.webp');

$im->setImageFormat('avif');
$im->writeImage('photo.avif');

Generate Responsive Images

$sizes = [320, 640, 1024, 1920];
$im = new Imagick('original.jpg');
$originalWidth = $im->getImageWidth();

foreach ($sizes as $width) {
    if ($width < $originalWidth) {
        $resized = clone $im;
        $resized->thumbnailImage($width, 0);
        $resized->writeImage("image-{$width}w.jpg");
    }
}

Extract Image Metadata

// Using PHP EXIF
$exif = exif_read_data('photo.jpg');
echo "Camera: " . ($exif['Make'] ?? 'Unknown') . "\n";
echo "Date: " . ($exif['DateTimeOriginal'] ?? 'Unknown') . "\n";

// Using exiftool (command line)
$output = shell_exec('exiftool -json photo.jpg');
$metadata = json_decode($output, true)[0];

Troubleshooting

HEIC Not Working

// Check HEIC support
$formats = Imagick::queryFormats('HEIC');
if (empty($formats)) {
    echo "HEIC not supported - libheif may be missing\n";
}

// Verify in container
// docker exec myapp php -r "print_r(Imagick::queryFormats('HEI*'));"

PDF Operations Fail

// Check Ghostscript
$gs = shell_exec('gs --version 2>&1');
echo "Ghostscript: " . ($gs ?: 'NOT INSTALLED') . "\n";

// Check ImageMagick policy
// docker exec myapp cat /etc/ImageMagick-7/policy.xml | grep PDF

Memory Issues with Large Images

// Increase memory limit
ini_set('memory_limit', '512M');

// Bound ImageMagick's own memory rather than the request's
$im = new Imagick();
$im->setResourceLimit(Imagick::RESOURCETYPE_MEMORY, 256 * 1024 * 1024);

Check What's Installed

# In container
docker exec myapp php -m | grep -E "gd|imagick"
docker exec myapp php -r "print_r(gd_info());"
docker exec myapp php -r "print_r(Imagick::queryFormats());"
docker exec myapp chromium-browser --version
docker exec myapp exiftool -ver
docker exec myapp gs --version

Related Guides: Available Extensions | Laravel Guide | Performance Tuning