README

A powerful, flexible, and easy-to-use image manipulation library for PHP with support for both GD and Imagick drivers. Perfect for handling image processing tasks with excellent quality preservation and animation support.

Features

🖼️ Dual Driver Support - Choose between GD or Imagick based on your needs
🎞️ Animation Support - Full animated GIF support
🎯 High Quality - Excellent quality preservation with optimized algorithms
📐 Multiple Operations - Resize, crop, rotate, flip, filters, and more
💧 Transparency Support - Full alpha channel support for PNG and GIF
🚀 Performance Optimized - Efficient memory usage and processing

Installation

composer require cleup/pixie

Requirements

PHP 8.1 or higher
GD extension (for GD driver)
Imagick extension (for Imagick driver - recommended for advanced features)
Gifsicle for better optimization of GIF images

Recommendation

If you plan to work with GIF images and want to optimize them or add animation support, it is recommended that you install Gifsicle. This tool can help you work with GIFs more efficiently and add animations where they are not currently supported, such as in conjunction with the GD library.

#  Ubuntu
sudo apt-get install gifsicle

# Centos
sudo yum install gifsicle

Quick Start

Using ImageManager (Recommended)

<?php
use Cleup\Pixie\ImageManager;

// Create from file with auto driver detection
$image = ImageManager::createFromPath('input.jpg');

// To optimize GIF performance, use Gifsicle
$image
    // Gifsicle will be available if installed
    ->useGifsicle()
    // If you want to get a minimum file size, you can select a value from 1 to 100.
    // The higher this value, the smaller the file size will be, but the frame quality may deteriorate.
    ->setGifsicleLossy(80);

// Allow upscaling - we do not recommend enabling it without need.
$image->upcale(true); // Default = false

// Resize and save
$image->resize(800, 600)
      ->save('output.jpg', 90);


// Create thumbnail
$image->fit(200, 200)
      ->greyscale()
      ->save('/path/to/thumbnail.jpg');

Using Image Class Directly

<?php

use Cleup\Pixie\Image;

// With specific driver
$image = new Image('imagick'); // or 'gd'
$image->load('input.png')
      ->resize(400, 300)
      ->save('/path/to/output.webp', 85, 'webp');

Driver Comparison

GD Driver

✅ Built-in PHP extension
✅ Good performance for basic operations
✅ Lower memory usage
❌ Does not support animated GIFs without Gifsicle
❌ Lower quality for some operations

Imagick Driver (Recommended)

✅ Excellent quality output
✅ Full animated GIF support
✅ Advanced image processing features
❌ Requires separate extension
❌ Higher memory usage

For most production applications, especially those that require support for animated GIF files or high-quality data output, we recommend using the Imagick driver in combination with the Gifsicle utility for optimal results.

Basic Usage

Loading Images

// From file
$image = ImageManager::createFromPath('/path/to/photo.jpg');

// From binary data
$data = file_get_contents('/path/to/photo.jpg');
$image = ImageManager::createFromString($data);

// From URL (with error handling)
try {
    // ✅ Correct
    $image = ImageManager::createFromString(
        file_get_contents('https://example.com/image.jpg')
    );

    // ❌ Incorrect
    $image = ImageManager::createFromPath('https://example.com/image.jpg');
} catch (Cleup\Pixie\Exceptions\ImageException $e) {
    echo "Error loading image: " . $e->getMessage();
}

Saving Images

// Save with default quality
$image->save('output.jpg');

// Save with specific quality and format
$image->save('output.webp', 85, 'webp');

// Output directly to browser
$image->output('jpeg', 90);

// Get as binary string
$binaryData = $image->toString('png', 100);

Image Operations

Resizing

// Basic resize
$image->resize(800, 600);

// Resize with aspect ratio preservation (default)
$image->resize(800, 600, true);

// Resize to specific width/height
$image->resizeToWidth(400);
$image->resizeToHeight(300);

// Scale by ratio
$image->scale(0.5); // 50% scale

// Fit within dimensions
$image->resizeToFit(1024, 768);

// Fill dimensions (crop to fit)
$image->resizeToFill(200, 200);

Cropping

// Crop with coordinates
$image->crop(100, 100, 400, 300);

// Fit and crop to exact dimensions
$image->fit(300, 300);

Transformations

// Rotation
$image->rotate(45); // 45 degrees
$image->rotate(90, '#FFFFFF'); // With background color

// Flipping
$image->flip('horizontal');
$image->flipHorizontal();
$image->flipVertical();

// Canvas operations
$image->resizeCanvas(1000, 800, 'center');

Filters and Effects

// Basic filters
$image->blur(2);
$image->sharpen(1);
$image->brightness(20);
$image->contrast(-10);
$image->gamma(1.2);

// Color effects
$image->greyscale();
$image->sepia();
$image->colorize(50, -20, 30);
$image->pixelate(10);
$image->invert();

Utility Methods

// Get image information
$width = $image->getWidth();
$height = $image->getHeight();
$ratio = $image->getAspectRatio();
$extension = $image->getExtension();
$isAnimated = $image->isAnimated(); // Imagick only

// Get driver instance
$driver = $image->getDriver();

Error Handling

use Cleup\Pixie\Exceptions\ImageException;
use Cleup\Pixie\Exceptions\DriverException;

try {
    $image = ImageManager::createFromPath('nonexistent.jpg');
    $image->resize(100, 100)->save('output.jpg');
} catch (ImageException $e) {
    echo "Image error: " . $e->getMessage();
} catch (DriverException $e) {
    echo "Driver error: " . $e->getMessage();
} catch (Exception $e) {
    echo "General error: " . $e->getMessage();
}

API Reference

ImageManager Static Methods

createFromPath(string $path, string $driver = 'auto'): Image
createFromString(string $data, string $driver = 'auto'): Image
getInfo(string $path): array
isSupportedFormat(string $path): bool
getAvailableDrivers(): array
isDriverAvailable(string $driver): bool
getRecommendedDriver(): string

Image Instance Methods

Loading & Saving

load(string $path): self
loadFromString(string $data): self
save(string $path, ?int $quality = null, ?string $format = null): bool
toString(?string $format = null, ?int $quality = null): string
output(?string $format = null, ?int $quality = null): void

Information

getWidth(): int
getHeight(): int
getAspectRatio(): float
getType(): string
getMimeType(): string
isAnimated(): bool
getDriver(): DriverInterface

Transformations

resize(int $width, ?int $height = null, bool $preserveAspectRatio = true): self
resizeToWidth(int $width): self
resizeToHeight(int $height): self
resizeToFit(int $maxWidth, int $maxHeight): self
resizeToFill(int $width, int $height): self
scale(float $ratio): self
crop(int $x, int $y, int $width, int $height): self
fit(int $width, int $height): self
rotate(float $angle, string $backgroundColor = 'transparent'): self
flip(string $mode = 'horizontal'): self
flipHorizontal(): self
flipVertical(): self

Filters & Effects

blur(int $amount = 1): self
sharpen(int $amount = 1): self
brightness(int $level): self
contrast(int $level): self
gamma(float $correction): self
colorize(int $red, int $green, int $blue): self
greyscale(): self
sepia(): self
pixelate(int $size): self
invert(): self
watermark($watermark, string $position = 'bottom-right', int $offsetX = 10, int $offsetY = 10): self

License

MIT License. See LICENSE file for details.

cleup / pixie

Maintainers

Details

README

Features

Installation

Requirements

Recommendation

Quick Start

Using ImageManager (Recommended)

Using Image Class Directly

Driver Comparison

GD Driver

Imagick Driver (Recommended)

Basic Usage

Loading Images

Saving Images

Image Operations

Resizing

Cropping

Transformations

Filters and Effects

Utility Methods

Error Handling

API Reference

ImageManager Static Methods

Image Instance Methods

Loading & Saving

Information

Transformations

Filters & Effects

License