https://github.com/gomzyakov/image-placeholder

🍉 Simple image placeholder generator on PHP
https://github.com/gomzyakov/image-placeholder

image-placeholder image-placeholders php placeholder placeholder-image placeholders placeholders-service

Last synced: 5 months ago
JSON representation

🍉 Simple image placeholder generator on PHP

• Host: GitHub
• URL: https://github.com/gomzyakov/image-placeholder
• Owner: gomzyakov
• License: mit
• Created: 2025-10-05T14:51:47.000Z (8 months ago)
• Default Branch: main
• Last Pushed: 2025-10-05T17:12:51.000Z (8 months ago)
• Last Synced: 2025-10-05T18:14:14.181Z (8 months ago)
• Topics: image-placeholder, image-placeholders, php, placeholder, placeholder-image, placeholders, placeholders-service
• Language: PHP
• Homepage: https://packagist.org/packages/gomzyakov/image-placeholder
• Size: 25.4 KB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Simple image placeholder generator on PHP

A simple package that allows you to create placeholder images for your PHP website.

### 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

### Examples

Below are sample outputs generated by this library:

![Image placeholder generated with PHP (example three)](tests/images/example_3.png) ![Image placeholder generated with PHP (example one)](tests/images/example_1.png) ![Image placeholder generated with PHP (example two)](tests/images/example_2.png)

### Requirements

- PHP 8.3+

- `ext-gd` enabled (for image creation and PNG encoding)

### Installation

```sh

composer require gomzyakov/image-placeholder

```

### Usage

```php

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

generate(48, 48, 'avatar-seed');

header('Content-Type: image/png');

header('Content-Length: ' . strlen($png));

echo $png;

```

### API

```php

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:

```sh

composer phpunit

```

### License

MIT — see [LICENSE](LICENSE).

### Support

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