README

A comprehensive PHP library for building URLs for ImgProxy, supporting all features including pro options.

This library is based on and extends the work of the onliner/imgproxy-php project, adding support for all ImgProxy features including Pro functionality.

Installation

The preferred way to install this extension is through composer.

composer require mperonnet/imgproxy-php

Features

• Full support for all ImgProxy options (including Pro features)
• URL signing and encryption
• Base64 and plain URL encoding
• Support for info endpoint
• Support for presets
• Support for chained pipelines (Pro)
• Type-safe option builders
• Immutable, fluent interface

Basic Usage

use Mperonnet\ImgProxy\UrlBuilder;
use Mperonnet\ImgProxy\Options\Width;
use Mperonnet\ImgProxy\Options\Height;
use Mperonnet\ImgProxy\Options\Quality;
use Mperonnet\ImgProxy\Options\Dpr;

$key = getenv('IMGPROXY_KEY');
$salt = getenv('IMGPROXY_SALT');

$src = 'http://example.com/image.jpg';

$builder = UrlBuilder::signed($key, $salt);
$builder = $builder->with(
    new Dpr(2),
    new Quality(90),
    new Width(300),
    new Height(400)
);
    
$url = $builder->url($src);  // Base64-encoded URL
$url = $builder->usePlain()->url($src); // Plain URL
$url = $builder->url($src, 'png'); // Change image format

URL Formats

Base64-encoded URL (default)

$url = $builder->useBase64()->url($src);
// Example: /9SaGqJILqstFsWthdP/dpr:2/q:90/w:300/h:400/aHR0cDovL2V4YW1wL2ltYWdlLmpwZw

Plain URL

$url = $builder->usePlain()->url($src);
// Example: /9SaGqJILqstFsWthdP/dpr:2/q:90/w:300/h:400/plain/http://example.com/image.jpg

Encrypted URL (Pro)

$encryptionKey = getenv('IMGPROXY_ENCRYPTION_KEY');
$url = $builder->useEncryption($encryptionKey)->url($src);
// Example: /9SaGqJILqstFsWthdP/dpr:2/q:90/w:300/h:400/enc/a1b2c3d4e5f6g7h8i9j0...

Advanced Features

Gravity

use Mperonnet\ImgProxy\Options\Gravity;
use Mperonnet\ImgProxy\Support\GravityType;

// Basic gravity
$builder->with(new Gravity(GravityType::CENTER));

// With offset
$builder->with(new Gravity(GravityType::NORTH_WEST, 10, 20));

// Smart gravity
$builder->with(Gravity::smart());

// Focus point gravity
$builder->with(Gravity::focusPoint(0.7, 0.3));

// Object detection gravity (Pro)
$builder->with(Gravity::object(['face', 'cat']));

// Weighted object detection gravity (Pro)
$builder->with(Gravity::objectWeighted(['face' => 2, 'cat' => 1]));

Watermark

use Mperonnet\ImgProxy\Options\Watermark;
use Mperonnet\ImgProxy\Options\WatermarkText;
use Mperonnet\ImgProxy\Options\WatermarkUrl;

// Basic watermark
$builder->with(Watermark::center(0.5, 10, 10, 0.3));

// Replicated watermark
$builder->with(Watermark::replicate(0.5));

// Custom watermark URL (Pro)
$builder->with(new WatermarkUrl('http://example.com/watermark.png'));

// Text watermark (Pro)
$builder->with(new WatermarkText('© Example Corporation'));

Info Endpoint (Pro)

use Mperonnet\ImgProxy\Options\InfoOptions;

// Basic info
$infoUrl = $builder->info()->with(InfoOptions::basic())->url($src);

// Complete info
$infoUrl = $builder->info()->with(InfoOptions::complete())->url($src);

// Custom info
$infoUrl = $builder->info()->with(
    new InfoOptions(
        true,  // size
        true,  // format
        true,  // dimensions
        false, // exif
        false, // iptc
        false, // xmp
        true,  // video_meta
        true   // detect_objects
    )
)->url($src);

Chained Pipelines (Pro)

use Mperonnet\ImgProxy\Options\Resize;
use Mperonnet\ImgProxy\Options\Blur;
use Mperonnet\ImgProxy\Options\Watermark;

// First resize, then blur and add watermark
$url = $builder
    ->with(new Resize('fit', 300, 300))
    ->pipeline(
        new Blur(10),
        Watermark::southEast(0.7)
    )
    ->url($src);

Additional Processing Options

Resizing and Dimensions

use Mperonnet\ImgProxy\Options\Resize;
use Mperonnet\ImgProxy\Options\Size;
use Mperonnet\ImgProxy\Options\Width;
use Mperonnet\ImgProxy\Options\Height;
use Mperonnet\ImgProxy\Options\MinWidth;
use Mperonnet\ImgProxy\Options\MinHeight;
use Mperonnet\ImgProxy\Options\Zoom;
use Mperonnet\ImgProxy\Options\Dpr;

$builder->with(
    new Resize('fill', 300, 400, true, false),
    new Size(300, 400, true, false),
    new Width(300),
    new Height(400),
    new MinWidth(200),
    new MinHeight(200),
    new Zoom(1.5),
    new Dpr(2)
);

Image Adjustments

use Mperonnet\ImgProxy\Options\Adjust;
use Mperonnet\ImgProxy\Options\Brightness;
use Mperonnet\ImgProxy\Options\Contrast;
use Mperonnet\ImgProxy\Options\Saturation;

$builder->with(
    new Adjust(10, 1.1, 0.9),
    new Brightness(10),
    new Contrast(1.1),
    new Saturation(0.9)
);

Color Effects

use Mperonnet\ImgProxy\Options\Background;
use Mperonnet\ImgProxy\Options\Blur;
use Mperonnet\ImgProxy\Options\Sharpen;
use Mperonnet\ImgProxy\Options\Monochrome;
use Mperonnet\ImgProxy\Options\Duotone;
use Mperonnet\ImgProxy\Options\Colorize;
use Mperonnet\ImgProxy\Options\Gradient;
use Mperonnet\ImgProxy\Support\Color;

$builder->with(
    new Background(new Color(255, 255, 255)),
    new Blur(5),
    new Sharpen(0.7),
    new Monochrome(0.8, 'b3b3b3'),
    new Duotone(0.8, '000000', 'ffffff'),
    new Colorize(0.5, '3498db', true),
    new Gradient(0.7, 'ff0000', 45, 0.2, 0.8)
);

Format and Quality

use Mperonnet\ImgProxy\Options\Format;
use Mperonnet\ImgProxy\Options\Quality;
use Mperonnet\ImgProxy\Options\FormatQuality;
use Mperonnet\ImgProxy\Options\Autoquality;
use Mperonnet\ImgProxy\Options\MaxBytes;

$builder->with(
    new Format('webp'),
    new Quality(85),
    new FormatQuality([
        'jpeg' => 85,
        'webp' => 80,
        'avif' => 60
    ]),
    Autoquality::dssim(0.02, 70, 85, 0.001),
    new MaxBytes(100000)
);

Object Detection (Pro)

use Mperonnet\ImgProxy\Options\BlurDetections;
use Mperonnet\ImgProxy\Options\DrawDetections;

$builder->with(
    new BlurDetections(5, ['face']),
    new DrawDetections(true, ['face', 'cat'])
);

Credits

This library is an extension of the onliner/imgproxy-php project with added support for ImgProxy Pro features and a more comprehensive API. We're grateful to the original authors for providing the foundation that made this extension possible.

License

Released under the MIT license.