cleup/pixie

An excellent library for working with images in PHP.

1.0.2 2025-10-29 12:26 UTC

Requires

• php: >=8.1

Requires (Dev)

• symfony/var-dumper: ^7.3

Suggests

• ext-gd: For working with the GD extension
• ext-imagick: For working with the Imagick extension

MIT

• Eduard Y

• php
• image
• crop
• scale
• pixie
• risize

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 with Imagick driver
• 🎯 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)

Quick Start

Using ImageManager (Recommended)

<?php
use Cleup\Pixie\ImageManager;

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

// 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('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('output.webp', 85, 'webp');

Driver Comparison

GD Driver

• ✅ Built-in PHP extension
• ✅ Good performance for basic operations
• ✅ Lower memory usage
• ❌ No animated GIF support
• ❌ Limited format support
• ❌ Lower quality for some operations

Imagick Driver (Recommended)

• ✅ Excellent quality output
• ✅ Full animated GIF support
• ✅ Wide format support (WebP, TIFF, etc.)
• ✅ Advanced image processing features
• ❌ Requires separate extension
• ❌ Higher memory usage

For most production applications, especially those requiring animated GIF support or highest quality output, we recommend using the Imagick driver.

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 {
    // Incorrect
    $image = ImageManager::createFromPath('https://example.com/image.jpg');
    /* Correct
    $image = ImageManager::createFromString(
        file_get_contents('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();
$type = $image->getType();
$isAnimated = $image->isAnimated(); // Imagick only

// Remove EXIF data
$image->stripExif();

// 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 = '#000000'): 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
• stripExif(): self

License

MIT License. See LICENSE file for details.