README

Professional PHP image resizing library with multiple driver support. Supports GD and Imagick drivers with a unified API.

Features

Multi-driver support: Choose between GD and Imagick drivers
Fluent API: Chainable methods for easy image manipulation
Multiple operations: Resize, crop, rotate, watermark, aspect ratio adjustments
Format support: JPEG, PNG, GIF, WebP
Extensible architecture: Easy to add custom drivers
PHP 8.1+: Modern PHP with type safety

Installation

composer require coderden/image-resizer

Quick Start

$processor = new ImageProcessor('gd'); // or 'imagick'

// Load, resize, and save
$processor->load('input.jpg')
    ->resize(800, 600)
    ->save('output.jpg', 85);

// Get image as string
$imageData = $processor->load('photo.png')
    ->crop(300, 300)
    ->get('webp', 80);

Usage Examples

Basic Resizing

$processor = new ImageProcessor();

// Resize with width only (maintains aspect ratio)
$processor->load('image.jpg')
    ->resize(800)
    ->save('resized.jpg');

// Resize with height only
$processor->load('image.jpg')
    ->resize(null, 600)
    ->save('resized.jpg');

// Resize to exact dimensions (may distort)
$processor->load('image.jpg')
    ->resize(800, 600)
    ->save('resized.jpg');

Cropping

// Crop to specific dimensions
$processor->load('image.jpg')
    ->crop(300, 200)
    ->save('cropped.jpg');

// Crop with custom position
$processor->load('image.jpg')
    ->crop(300, 200, 100, 50) // x=100, y=50
    ->save('cropped.jpg');

Aspect Ratio

// Crop to 16:9 aspect ratio
$processor->load('image.jpg')
    ->aspectRatio(16/9)
    ->save('widescreen.jpg');

// Crop to square with top alignment
$processor->load('image.jpg')
    ->aspectRatio(1, 'top')
    ->save('square-top.jpg');

// Available positions: 'center', 'top', 'bottom', 'left', 'right'

Rotation

// Rotate 45 degrees
$processor->load('image.jpg')
    ->rotate(45)
    ->save('rotated.jpg');

// Rotate -90 degrees (counter-clockwise)
$processor->load('image.jpg')
    ->rotate(-90)
    ->save('rotated.jpg');

Watermark

// Add watermark
$processor->load('image.jpg')
    ->watermark('watermark.png', 'bottom-right', 50)
    ->save('watermarked.jpg');

// Available positions: 
// 'top-left', 'top-right', 'bottom-left', 'bottom-right', 'center'

Driver Selection

// Use GD driver (default)
$processor = new ImageProcessor('gd');

// Use Imagick driver (requires ext-imagick)
$processor = new ImageProcessor('imagick');

// Use specific driver for operation
$image = $processor->driver('imagick')
    ->load('image.tiff')
    ->resize(800, 600)
    ->get('jpg');

Getting Image Data

// Get as binary string
$jpegData = $processor->load('image.png')
    ->resize(800, 600)
    ->get('jpg', 85);

// Get image dimensions
$dimensions = $processor->load('image.jpg')
    ->getDimensions();
// Returns: ['width' => 1920, 'height' => 1080]

Static Helper Usage

The package includes a static helper class Resizer for quick and easy image processing.

Basic Static Usage

use CoderDen\ImageResizer\Resizer;

// Quick resize and save
Resizer::resize('input.jpg', 'output.jpg', 800, 600);

// Load and process with method chaining
Resizer::load('image.jpg')
    ->resize(300, 200)
    ->rotate(90)
    ->save('processed.jpg');

// Use different driver
Resizer::driver('imagick')
    ->load('image.tiff')
    ->save('output.jpg');

Quick Helper Methods

// Quick thumbnail creation
Resizer::thumbnail('photo.jpg', 'thumb.jpg', 150, true, 85);

// Quick crop
Resizer::crop('image.jpg', 'cropped.jpg', 300, 200);

// Get image dimensions
$size = Resizer::getImageSize('photo.jpg');
echo "Width: {$size['width']}, Height: {$size['height']}";

// Convert format
Resizer::convertFormat('input.png', 'output.webp', 'webp', 80);

// Base64 operations
$base64 = Resizer::toBase64('image.jpg', 800, 600);
Resizer::fromBase64($base64, 'output.jpg');

Batch Processing

$images = [
    [
        'input' => 'image1.jpg',
        'output' => 'thumb1.jpg',
        'width' => 150,
        'height' => 150,
    ],
    [
        'input' => 'image2.jpg',
        'output' => 'thumb2.jpg',
        'width' => 200,
        'height' => 200,
    ],
];

$results = Resizer::batchProcess($images, function($processor, $image) {
    return $processor
        ->resize($image['width'], $image['height'])
        ->save($image['output'], 85);
});

Driver Configuration

// Set default driver
Resizer::setDefaultDriver('imagick');

// Use specific driver
Resizer::driver('gd')
    ->load('image.jpg')
    ->resize(800, 600);

Advanced Usage

Custom Driver

$processor = new ImageProcessor();

// Register custom driver
$processor->extend('custom', function () {
    return new class implements DriverInterface {
        // Implement all required methods
        public function load($source): self { /* ... */ }
        public function resize(?int $width = null, ?int $height = null): self { /* ... */ }
        // ... other methods
    };
});

// Use custom driver
$processor->driver('custom')
    ->load('image.jpg')
    ->resize(800, 600);

Error Handling

try {
    $processor = new ImageProcessor('imagick');
    $processor->load('nonexistent.jpg')
        ->resize(800, 600)
        ->save('output.jpg');
} catch (ImageDriverException $e) {
    // Driver-related errors (extension not loaded, etc.)
    echo "Driver error: " . $e->getMessage();
} catch (ImageProcessingException $e) {
    // Image processing errors
    echo "Processing error: " . $e->getMessage();
} catch (Exception $e) {
    // Other errors
    echo "Error: " . $e->getMessage();
}

API Reference

ImageProcessor Methods

driver(?string $driver = null): DriverInterface - Get driver instance
getDefaultDriver(): string - Get default driver name
extend(string $name, callable $callback): void - Register custom driver

Driver Methods

All methods return $this for chaining except where noted.

load(string|resource $source): self - Load image from file or resource
resize(?int $width = null, ?int $height = null): self - Resize image
crop(int $width, int $height, ?int $x = null, ?int $y = null): self - Crop image
aspectRatio(float $ratio, string $position = 'center'): self - Crop to aspect ratio
rotate(float $angle): self - Rotate image
watermark(string $watermarkPath, string $position = 'bottom-right', int $opacity = 100): self - Add watermark
save(string $path, int $quality = 90, ?string $format = null): bool - Save to file
get(?string $format = null, int $quality = 90): string - Get as binary string
getDimensions(): array - Get image dimensions
destroy(): void - Free resources

Requirements

PHP 8.1 or higher
GD extension (required)
Imagick extension (optional, for Imagick driver)

coderden / image-resizer

Maintainers

Details