gomzyakov/image-placeholder

Simple image placeholder generator on PHP

v1.0.0 2025-10-05 17:01 UTC

Requires

• php: ^8.3
• ext-gd: *
• kornrunner/blurhash: ^1.2

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.62
• gomzyakov/code-style: ^2.0
• mockery/mockery: ^1.6
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.0
• rector/rector: ^2.1

MIT

• Alexander Gomzyakov

• generator
• php
• image
• placeholder

README

Generate small, deterministic placeholder images using BlurHash and PHP GD.

Features

• 🍴 Deterministic output by seed
• 🌇 PNG binary output ready to save or stream
• 🐊 Size and component bounds clamped for safety
• 👌 Zero external binaries; pure PHP + GD

Requirements

• PHP 8.3+
• ext-gd enabled (for image creation and PNG encoding)

Installation

composer require gomzyakov/image-placeholder

Usage

<?php

use Gomzyakov\ImagePlaceholder;

$generator = new ImagePlaceholder();

// Generate a 320x180 PNG as binary string (deterministic by seed)
$png = $generator->generate(320, 180, seed: 'my-seed', cx: 4, cy: 3);

// Save to disk
file_put_contents(__DIR__ . '/placeholder.png', $png);

Send as HTTP response

<?php

use Gomzyakov\ImagePlaceholder;

$generator = new ImagePlaceholder();
$png = $generator->generate(48, 48, 'avatar-seed');

header('Content-Type: image/png');
header('Content-Length: ' . strlen($png));
echo $png;

API

string ImagePlaceholder::generate(
    int $width,
    int $height,
    string $seed = 'default',
    int $cx = 4,
    int $cy = 3
)

• width, height: Target image size in pixels. Clamped to [1..2000].
• seed: Any string. Same inputs → identical output PNG.
• cx, cy: BlurHash component counts. Clamped to [1..9].

Returns a PNG binary string. Throws RuntimeException if image creation fails.

Determinism

The placeholder is generated from a pseudo-random source seeded by seed. Using the same tuple (width, height, seed, cx, cy) produces identical PNG output.

Testing

Run the test suite:

composer phpunit

License

MIT — see LICENSE.

Support

Found an issue or have a suggestion? Please open an issue in the repository: https://github.com/gomzyakov/image-placeholder.