README

picturium PHP client

A tiny, dependency-free PHP client for picturium.
Build signed media URLs and responsive <img> / <picture> markup without template clutter.

Why this library?

Your templates describe an image; picturium PHP turns that description into the correct URL or HTML. It handles query-string encoding, URL signing, DPR srcsets, responsive sources, and intrinsic dimensions.

It works with plain PHP, Blade, Twig, Latte, or any view layer that accepts a string. The media processing happens in the picturium server.

Install

composer require lamka02sk/picturium

PHP 8.4 or newer is required.

Start here

Configure the server once during application boot. Omit secret only when signing is disabled on the server.

use Picturium\Enum\Format;
use Picturium\Picturium;

use function Picturium\img;

Picturium::configure(
    url: 'https://img.example.com',
    secret: $_ENV['PICTURIUM_SECRET'],
    defaults: img()->dpr([1, 2, 3])->quality(80)->format(Format::Auto),
);

Then let the library render the complete, escaped image element:

<?= img($product->photo)
    ->width(640)
    ->aspectRatio('4/3')
    ->alt($product->name)
    ->lazy() ?>

Or use only the piece your template needs:

$image = img('photos/cat.jpg')->width(400)->dpr([1, 2]);

$image->src();        // One signed URL
$image->srcset();     // "... 1x, ... 2x"
$image->urls();       // ['1x' => '...', '2x' => '...']
$image->attributes(); // Raw attribute array for framework adapters
$image->attrs();      // Escaped attributes for an existing <img>
$image->toHtml();     // A complete <img> element

<img <?= img($product->photo)->width(400)->attrs() ?> alt="<?= $product->name ?>">

Responsive art direction

Use picture() when the image itself should change at a breakpoint. Put the most specific source first; the browser selects the first matching source.

use Picturium\Enum\Format;

use function Picturium\picture;

<?= picture('hero.jpg')
    ->quality(80)
    ->dpr([1, 2])
    ->images(fn ($image) => [
        $image->maxWidth(640)->portrait()->width(640)->aspectRatio('1/1'),
        $image->minWidth(641)->format(Format::Avif)->width(1920)->height(1080),
    ])
    ->alt('A mountain at sunrise') ?>

Each source is an independent image. Shared settings such as quality and DPR apply to every source; media helpers include minWidth(), maxWidth(), portrait(), landscape(), and media().

Image controls

Every picturium URL parameter has a typed setter. Use enums for fixed choices and named arguments for grouped controls:

use Picturium\Enum\{Anchor, Extend, Fit, Format, Gravity, Metadata, Resample, Rotate};

img('catalogue/shoes.jpg')
    ->width(800)->height(600)->aspectRatio('4/3')
    ->fit(Fit::Contain)->gravity(Gravity::Attention)->extend(Extend::Mirror)
    ->resample(Resample::Lanczos3)->upsize()->padding(10, 20)
    ->rotate(Rotate::Left)->background('111827')
    ->quality(82)->format(Format::Webp)->metadata(Metadata::Icc)
    ->crop(width: 800, height: 600, gravity: Gravity::Attention)
    ->watermark(text: 'ACME', anchor: Anchor::BottomRight, opacity: 40)
    ->download('shoes.webp');

Short aliases are available when URLs are the main concern: w(), h(), ar(), q(), f(), g(), bg(), and more.

Good to know

Images are immutable by default, so one configured image can safely create desktop and mobile variants.
When both dimensions—or one dimension and an aspect ratio—are known, generated HTML includes width and height to prevent layout shift.
dpr([1, 2, 3]) generates an x-descriptor srcset. Use <picture> for breakpoint-specific layouts.
URLs use a stable parameter order, keeping signatures and CDN cache keys repeatable.
Signed URLs do not expire. Rotate the server secret to invalidate them.

Need bare global helpers? Opt in once:

require 'vendor/lamka02sk/picturium/src/globals.php';

Development

composer install
composer test
composer stan

The integration signature test is skipped unless a server is available:

PICTURIUM_URL=http://127.0.0.1:20046 PICTURIUM_SECRET=testsecret composer test

The server

This package builds requests; picturium does the transformation, caching, and media delivery. See the main project for server configuration and supported formats.

License

MIT. See LICENSE.

lamka02sk / picturium

Maintainers

Package info

Statistics

Security