PHPackages                             exeque/placehold-dot-co - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Image & Media](/categories/media)
4. /
5. exeque/placehold-dot-co

ActiveLibrary[Image & Media](/categories/media)

exeque/placehold-dot-co
=======================

Wrapper for Placehold.co placeholder images

0.1.1(1y ago)00MITPHPPHP ^8.2CI passing

Since Mar 29Pushed 1y ago1 watchersCompare

[ Source](https://github.com/ExeQue/php-placehold-dot-co)[ Packagist](https://packagist.org/packages/exeque/placehold-dot-co)[ RSS](/packages/exeque-placehold-dot-co/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (11)Versions (3)Used By (0)

Placehold.co
============

[](#placeholdco)

Wrapper for [placehold.co](https://placehold.co/) to generate placeholder images.

It supports the full API of [placehold.co](https://placehold.co/) and provides a fluent interface to build the images.

Installation
------------

[](#installation)

You can install this package via composer:

```
composer require exeque/placehold-dot-co
```

Usage
-----

[](#usage)

### The Image Object

[](#the-image-object)

The image object contains the following properties:

- `size`: The size of the image in bytes.
- `contents`: The contents of the image as a string.
- `mime`: The mime type of the image.
- `uri`: The URI of the image.

The image is stored using a `php://temp` resource to reduce memory usage. The resource is automatically closed when the object is destroyed.

### Basic Usage

[](#basic-usage)

Images can be generated using the `builder()` method.

The `Builder` class provides an immutable fluent interface to build the image.

```
use ExeQue\PlaceholdDotCo\Data\Format;
use ExeQue\PlaceholdDotCo\Data\Image;
use ExeQue\PlaceholdDotCo\Placehold;

$placehold = new Placehold();

/** @var Image $image */
$image = $placehold->builder()
    ->size(1920, 1080)
    ->color('black', 'white')
    ->format(Format::JPEG)
    ->text('Hello World')
    ->get();

$image->size; // Byte size
$image->contents; // Image contents as string
$image->mime; // Image mime type
$image->uri; // Image URI
$image->detach(); // Detach the data stream from the object
```

### Size

[](#size)

By default, the images are created as 300x300, but you can change the size.

```
use ExeQue\PlaceholdDotCo\Placehold;

$placehold = new Placehold();

$builder = $placehold->builder();

$builder->size(1920, 1080);
$builder->width(1920);
$builder->height(1080);
$builder->square(1000);
```

It is also possible to change the orientation of the image by using the `landscape()` and `portrait()` methods.

```
use ExeQue\PlaceholdDotCo\Placehold;

$placehold = new Placehold();

$landscape = $placehold->builder()->size(1920, 1080); // landscape 1920x1080
$portrait = $placehold->builder()->size(1080, 1920); // portrait 1080x1920

$landscape->portrait(); // landscape 1920x1080 -> portrait 1080x1920
$portrait->landscape(); // portrait 1080x1920 -> landscape 1920x1080
```

#### Retina

[](#retina)

You can also create retina images by using the `retina()` method.

Only supported for:

- JPEG
- PNG
- GIF
- WEBP
- AVIF

```
use ExeQue\PlaceholdDotCo\Placehold;

$builder = $placehold->builder();

$builder->x1(); // no retina / reset
$builder->x2(); // retina 2x
$builder->x3(); // retina 3x
```

### Format

[](#format)

You can change the image format by using the `format()` or format specific methods.

```
use ExeQue\PlaceholdDotCo\Data\Format;
use ExeQue\PlaceholdDotCo\Placehold;

$placehold = new Placehold();

$builder = $placehold->builder();

// JPEG
$builder->format(Format::JPEG);
$builder->jpeg();

// PNG
$builder->format(Format::PNG);
$builder->png();

// GIF
$builder->format(Format::GIF);
$builder->gif();

// WEBP
$builder->format(Format::WEBP);
$builder->webp();

// SVG
$builder->format(Format::SVG);
$builder->svg();

// AVIF
$builder->format(Format::AVIF);
$builder->avif();
```

### Color

[](#color)

You can change the background and text color by using the `color()`, `background()` or `foreground()` methods.

Note: If you're using the `foreground()` method without a background color set it will set the background color to white.

The methods support CSS colors, hex colors (without #), and transparency (via the `transparent` color).

```
use ExeQue\PlaceholdDotCo\Data\Format;
use ExeQue\PlaceholdDotCo\Placehold;

$placehold = new Placehold();

$builder = $placehold->builder();

$builder->color('black', 'white'); // background black, text white
$builder->color('F00', 'FFF'); // background #F00, text #FFF
$builder->color('FF0000', 'FFFFFF'); // background #FF0000, text #FFFFFF
$builder->color('transparent', 'black'); // background transparent, text black

$builder->background('black'); // background black
$builder->foreground('black'); // text black (background white)
```

### Text

[](#text)

You can change the text by using the `text()` method. Existing text will be overwritten - Existing text can be removed by using the `noText()` method.

Multiline text is supported and lines are separated by `\n`.

```
use ExeQue\PlaceholdDotCo\Placehold;

$placehold = new Placehold();

$builder = $placehold->builder();

$builder->text('Hello World'); // Single line "Hello World"
$builder->text("Hello\nWorld"); // Multi line text "Hello\nWorld"

$builder->noText(); // remove text
```

### Font

[](#font)

You can change the font by using the `font()` or specific font methods.

```
use ExeQue\PlaceholdDotCo\Data\Font;
use ExeQue\PlaceholdDotCo\Placehold;

$placehold = new Placehold();

$builder = $placehold->builder();

// Lato
$builder->font(Font::Lato);
$builder->lato();

// Lora
$builder->font(Font::Lora);
$builder->lora();

// Montserrat
$builder->font(Font::Montserrat);
$builder->montserrat();

// Noto Sans
$builder->font(Font::NotoSans);
$builder->notoSans();

// Open Sans
$builder->font(Font::OpenSans);
$builder->openSans();

// Oswald
$builder->font(Font::Oswald);
$builder->oswald();

// Playfair Display
$builder->font(Font::PlayfairDisplay);
$builder->playfairDisplay();

// Poppins
$builder->font(Font::Poppins);
$builder->poppins();

// PT Sans
$builder->font(Font::PTSans);
$builder->ptSans();

// Raleway
$builder->font(Font::Raleway);
$builder->raleway();

// Roboto
$builder->font(Font::Roboto);
$builder->roboto();

// Source Sans Pro
$builder->font(Font::SourceSansPro);
$builder->sourceSansPro();
```

### Conditional Methods

[](#conditional-methods)

If you want to use the builder methods conditionally, you can use the `when()` method.

```
use ExeQue\PlaceholdDotCo\Builder;
use ExeQue\PlaceholdDotCo\Placehold;

$placehold = new Placehold();

$builder = $placehold->builder();

$condition = true;
$callableCondition = fn() => true;

$builder
    ->when($condition, fn(Builder $builder) => $builder->square(400))
    ->when($callableCondition, fn(Builder $builder) => $builder->square(400));
```

URL Generation
--------------

[](#url-generation)

You can also generate the URL for the image by using the `url()` method.

```
use ExeQue\PlaceholdDotCo\Placehold;

$builder = $placehold->builder();

$builder->uri(); // URI of the image as a PSR-7 compatible UriInterface
```

Advanced Usage
--------------

[](#advanced-usage)

### Batching

[](#batching)

The library supports fetching multiple images at once using the `batch()` method by leveraging the `Guzzle` library's async requests.

You are not guaranteed to get the images in the same order as you requested them, so you should use the keys to identify the images if order matters.

```
use ExeQue\PlaceholdDotCo\Placehold;

$placehold = new Placehold();

$builder = $placehold->builder()->size(1920, 1080)->png();

// The batch method returns a generator function that can be used to fetch the images. Any indices can be used as keys.
$generator = $placehold->batch([
    'first' => $builder->text('First Image'),
    'second' => $builder->text('Second Image'),
]);

foreach ($generator as $index => $image) {
    // Do something with the image
}

// The generator function will return the images as they are fetched.
$images = iterator_to_array($generator);

$images['first']; // URI of the first image
$images['second']; // URI of the second image
```

### Caching

[](#caching)

The library supports caching the images to optimize performance.

By default, the library uses the `php://temp` stream to store the images. The cache is handled on the internal HTTP client.

```
use ExeQue\PlaceholdDotCo\Cache\ImageStore;
use ExeQue\PlaceholdDotCo\Client;
use ExeQue\PlaceholdDotCo\Placehold;

// Store the images in system temp directory (default)
$store = ImageStore::temp();

// Store the images in a custom directory
$store = ImageStore::file('path/to/cache');

// Store the images in memory
$store = ImageStore::memory();

// Store the images in a null store (no caching)
$store = ImageStore::null();

$placehold = new Placehold(
    new Client(
        imageStore: $store
    )
)
```

You can also create custom stores by implementing the `ExeQue\PlaceholdDotCo\Cache\Contracts\ImageStore` interface.

FakerPHP Provider
-----------------

[](#fakerphp-provider)

This library also provides a FakerPHP provider to generate placeholder images.

Most, but not all, features are available in the `Faker` provider.

Check the phpdoc for the `ImageProvider` class for more information.

```
use ExeQue\PlaceholdDotCo\Faker\ImageProvider;
use ExeQue\PlaceholdDotCo\Placehold;
use Faker\Factory;
use Faker\Generator;

$provider = new ImageProvider(
    new Placehold() // [Optional] Can be configured with a Placehold instance
);

/** @var Generator|ImageProvider $faker */
$faker = Factory::create();

$faker->addProvider($provider);

$faker->placeholdCoUrl();       // Create a url for a placeholder image
$faker->placeholdCoImage();     // Create a placeholder image as a string
$faker->placeholdCoResource();  // Create a placeholder image as a resource
```

Testing
-------

[](#testing)

You can run the tests using the following command:

```
composer test           # run unit tests
composer test:coverage  # run unit tests with coverage
composer test:types     # run type coverage tests

composer test:all       # run all tests
```

License
-------

[](#license)

This library is open-sourced software licensed under the [MIT license](LICENSE.md).

###  Health Score

25

—

LowBetter than 37% of packages

Maintenance46

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

415d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/23560353?v=4)[Morten Harders](/maintainers/ExeQue)[@ExeQue](https://github.com/ExeQue)

---

Top Contributors

[![ExeQue](https://avatars.githubusercontent.com/u/23560353?v=4)](https://github.com/ExeQue "ExeQue (15 commits)")

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/exeque-placehold-dot-co/health.svg)

```
[![Health](https://phpackages.com/badges/exeque-placehold-dot-co/health.svg)](https://phpackages.com/packages/exeque-placehold-dot-co)
```

###  Alternatives

[danog/madelineproto

Async PHP client API for the telegram MTProto protocol.

3.4k855.0k18](/packages/danog-madelineproto)[opentok/opentok

OpenTok is a platform for creating real time streaming video applications, created by TokBox.

1413.0M10](/packages/opentok-opentok)[guanguans/notify

Push notification SDK(AnPush、Bark、Chanify、DingTalk、Discord、Gitter、GoogleChat、IGot、Lark、Mattermost、MicrosoftTeams、NowPush、Ntfy、Push、Pushback、PushBullet、PushDeer、PushMe、Pushover、PushPlus、QQ、RocketChat、ServerChan、ShowdocPush、SimplePush、Slack、Telegram、WeWork、WPush、XiZhi、YiFengChuanHua、ZohoCliq、ZohoCliqWebHook、Zulip).

682104.9k7](/packages/guanguans-notify)[godruoyi/ocr

The Best Image Ocr SDK For BAT.

19314.7k1](/packages/godruoyi-ocr)[automattic/wistia-php

PHP wrapper for Wistia API

1431.9k](/packages/automattic-wistia-php)[daun/statamic-placeholders

Generate low-quality image placeholders for lazyloading Statamic assets

106.6k](/packages/daun-statamic-placeholders)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)