README

A modular, stateless image processing toolkit for PHP built on Imagick.
Compose powerful pipelines with simple, reusable operations for resizing, cropping, transforming, filtering, watermarking, and more.

✨ Features

• Composable: Chain any number of operations for advanced image workflows
• Rich Operations: Resize, crop, fit, filter, overlay, watermark, rotate, background, and more
• Strict typing: PHP 8.1+, PSR-4, Psalm/PHPStan ready
• No /tmp clutter: Uses dedicated temp folders for all operations
• Modern API: Pass closures or handler objects for complete flexibility
• Robust: Handles missing files, fallbacks, and generates placeholder images automatically

📦 Installation

composer require dalpras/image-processor

Or, add to your composer.json:

{
  "require": {
    "dalpras/image-processor": "^1.0"
  }
}

🚀 Quick Start

use DalPraS\Image\ImageProcessor;
use DalPraS\Image\Handlers\ImageResize;
use DalPraS\Image\Handlers\ImageCrop;
use DalPraS\Image\Handlers\ImageFit;
use DalPraS\Image\Handlers\ImageOverlay;
use DalPraS\Image\Handlers\ImageWatermark;
use DalPraS\Image\Handlers\ImageTransform;
use DalPraS\Image\Handlers\ImageFilter;

$processor = new ImageProcessor(__DIR__ . '/tmp');

// Compose a processing pipeline:
$operations = [
    ImageResize::resize(800, 600),
    ImageFit::fitToTarget(400, 300, 'fill'),
    ImageOverlay::overlay("Demo", 50, 50, null, 32, 'white', 0.7),
    ImageWatermark::watermark(__DIR__.'/logo.png', 'bottom-right', 0.3),
    ImageTransform::rotate(15),
    ImageFilter::filter('grayscale')
];

// Process the image:
$info = $processor->process(
    __DIR__ . '/input.jpg',
    [
        'outputDir'   => __DIR__ . '/out',
        'outputExt'   => 'webp',
        'operations'  => $operations,
        'fallback'    => __DIR__ . '/fallback.jpg',
    ]
);

echo $info->getWidth() . ' x ' . $info->getHeight();
echo $info->getInlinePng(); // Data URI for HTML <img src="">

🛠️ Supported Operations

All operations return an ImageHandle for use in the operations pipeline.

Resize

• resize(int $width, int $height, bool $keepAspect = true): ImageHandle
• resizeByRatio(int $dim, bool $isWidth = true): ImageHandle

Fit/Fill

• fitToTarget(int $targetWidth, int $targetHeight, string $mode = 'fit', string $anchor = 'center', string $background = 'white'): ImageHandle
  • Modes: fit, fitWidth, fitHeight, fill

Crop & Trim

• crop(int $width, int $height, int $x, int $y): ImageHandle
• trim(string $background = 'white'): ImageHandle

Background

• backgroundColor(string $color): ImageHandle
  • Sets the image background color (useful before flattening or composing).

Clip (Alpha Mask)

• clipPath(bool $inside = false): ImageHandle
  • Uses 8BIM clipping path #1 for precise masking.

Overlay (Text)

• overlay(string $text, int $x, int $y, string $font = null, int $size = 20, string $color = 'black', ?float $opacity = null, int $angle = 0, int $align = Imagick::ALIGN_LEFT): ImageHandle
  • Adds text overlay at specified coordinates with style options.

Transform

• rotate(float $degrees): ImageHandle
  • Rotates image by specified degrees.

Watermark

• watermark(string $path, string $position = 'center', ?float $opacity = null): ImageHandle
  • Overlays an image as a watermark. Supports all corners and center.

Filter

• filter(string $type, ...$args): ImageHandle
  • Image filters supported:
    • grayscale
    • sepia (optionally with threshold)
    • blur (with radius & sigma)
    • Extend with more as needed!

📋 API Reference

ImageProcessor

• __construct(?string $tempDir = null)
• process(string $imagePath, array $options = []): ImageInfo

Options

ImageInfo

Returned from process().
Extends SplFileInfo, with:

• getWidth(): int
• getHeight(): int
• getRatio(): float
• getInlinePng(): string — Data URI for HTML <img src>
• getSpaceHolder(): string — SVG placeholder (for lazy loading, etc.)

🐘 Symfony Integration Example

# services.yaml
DalPraS\Image\ImageProcessor:
    arguments: ['%kernel.cache_dir%/imagick-tmp']
    public: true

🧪 Testing

composer install
vendor/bin/phpunit

🤝 Contributions

Contributions are welcome!
Open an issue or submit a pull request.

📄 License

MIT © Stefano Dal Prà