README

PictoMock is a lightweight, framework-agnostic PHP library for generating fake placeholder images — perfect for testing, seeding databases, and prototyping. It supports SVG (zero dependencies), PNG, JPEG, GIF, WebP, and WBMP via the GD extension, with a clean fluent API and first-class Laravel and FakerPHP integration.

Features

Generate placeholder images in SVG, PNG, JPEG, GIF, WebP, WBMP
SVG generation requires no GD extension — works anywhere PHP runs
Fluent, immutable builder API for readable configuration
Simple static API for one-liners
Background color strategies: random solid color, fixed hex color, two-color gradient
Optional text overlay showing image dimensions (e.g. "400x300")
Laravel service provider, facade, and publishable config
FakerPHP provider for seamless integration with Faker-based factories
PHP 8.1+, strict types, PSR-4, PSR-12

Installation

composer require laratusk/pictomock

For raster image formats (PNG, JPEG, GIF, WebP, WBMP) the PHP GD extension is required:

# On Ubuntu/Debian:
sudo apt-get install php-gd

# On macOS with Homebrew:
brew install php && brew install gd

Quick Start

use Laratusk\PictoMock\PictoMock;

// Fluent API
$path = PictoMock::make()
    ->width(400)
    ->height(300)
    ->format('png')
    ->save('/tmp/images');

// Static one-liner
$path = PictoMock::generate('/tmp/images', 400, 300, 'png');

// SVG — no GD needed
$path = PictoMock::make()->format('svg')->width(800)->height(600)->save('/tmp');

// With dimension text overlay
$path = PictoMock::make()->format('png')->width(300)->height(200)->withText()->save('/tmp');

Usage

Static API

use Laratusk\PictoMock\PictoMock;

$path = PictoMock::generate(
    outputDir: '/tmp/images',
    width: 400,
    height: 300,
    format: 'jpeg',
);

Signature:

PictoMock::generate(
    string $outputDir,
    int $width = 300,
    int $height = 300,
    string|ImageFormat $format = 'png',
    ?BackgroundStrategyInterface $background = null,
    bool $showText = false,
    ?string $filename = null,
): string

Fluent API

use Laratusk\PictoMock\PictoMock;

$path = PictoMock::make()
    ->width(1200)
    ->height(628)
    ->format('webp')
    ->withText()
    ->filename('og-image')     // custom filename (without extension)
    ->save('/var/www/public/images');

The builder is immutable — each method returns a new instance, making it safe to fork:

$base = PictoMock::make()->width(400)->height(300);
$png  = $base->format('png')->save('/tmp');
$svg  = $base->format('svg')->save('/tmp');

Background Strategies

Random Color (default)

use Laratusk\PictoMock\BackgroundStrategies\RandomColor;

$path = PictoMock::make()
    ->background(new RandomColor())
    ->format('svg')
    ->save('/tmp');

Fixed Color

use Laratusk\PictoMock\BackgroundStrategies\FixedColor;

$path = PictoMock::make()
    ->background(new FixedColor('#4a90e2'))   // accepts #RRGGBB or #RGB
    ->format('png')
    ->save('/tmp');

Gradient Color

use Laratusk\PictoMock\BackgroundStrategies\GradientColor;

$path = PictoMock::make()
    ->background(new GradientColor('#ff6b6b', '#4ecdc4'))
    ->width(800)
    ->height(400)
    ->format('png')
    ->save('/tmp');

The gradient is rendered left-to-right for GD images and as an SVG linearGradient for SVG output.

Text Overlay

Add the image dimensions as a centered text label:

$path = PictoMock::make()
    ->width(400)
    ->height(300)
    ->format('png')
    ->withText()          // renders "400x300" centered on the image
    ->save('/tmp');

// Or pass false to disable explicitly:
$path = PictoMock::make()->withText(false)->format('svg')->save('/tmp');

SVG Generation (no GD required)

$path = PictoMock::make()
    ->format('svg')
    ->width(1200)
    ->height(630)
    ->background(new GradientColor('#667eea', '#764ba2'))
    ->withText()
    ->save('/tmp/social-images');

The SVG generator uses PHP's built-in DOMDocument and requires only ext-dom.

Laravel Integration

Auto-Discovery

The service provider and facade are auto-discovered via composer.json extra.laravel. No manual registration needed for Laravel 5.5+.

Publish Config

php artisan vendor:publish --tag=pictomock-config

This publishes config/pictomock.php to your application.

Facade

use Laratusk\PictoMock\Laravel\PictoMockFacade as PictoMock;
// or with the alias:
use PictoMock;

$path = PictoMock::make()->format('svg')->width(400)->height(300)->save(storage_path('app/images'));

Config Reference

// config/pictomock.php
return [
    'width'            => 300,
    'height'           => 300,
    'format'           => 'png',
    'show_text'        => false,
    'output_dir'       => storage_path('app/pictomock'),
    'background'       => 'random',       // 'random' | 'fixed' | 'gradient'
    'background_color' => '#4a90e2',      // used when background = 'fixed'
    'gradient_colors'  => ['#4a90e2', '#7b2ff7'],  // used when background = 'gradient'
];

Database Factories with FakerPHP

// app/Providers/AppServiceProvider.php
use Laratusk\PictoMock\Faker\PictoMockFakerProvider;

public function register(): void
{
    $this->app->extend(\Faker\Generator::class, function ($faker) {
        $faker->addProvider(new PictoMockFakerProvider($faker, storage_path('app/pictomock')));
        return $faker;
    });
}

Then use it in factories:

// database/factories/PostFactory.php
public function definition(): array
{
    return [
        'title'         => $this->faker->sentence(),
        'thumbnail'     => $this->faker->pictoMock(800, 450, 'webp'),
        'thumbnail_url' => $this->faker->pictoMockUrl(800, 450, 'png'),
    ];
}

FakerPHP Integration (Standalone)

use Faker\Factory;
use Laratusk\PictoMock\Faker\PictoMockFakerProvider;

$faker = Factory::create();
$faker->addProvider(new PictoMockFakerProvider($faker, '/tmp/images'));

// Returns absolute path to the generated file
$path = $faker->pictoMock(400, 300, 'png');

// Returns data URI (data:image/png;base64,...)
$dataUri = $faker->pictoMockUrl(400, 300, 'svg');

// With dimension text overlay
$path = $faker->pictoMock(800, 600, 'jpeg', true);

Available Faker Methods

Method	Description
`pictoMock(int $w, int $h, string $format, bool $text)`	Generate image and return file path
`pictoMockUrl(int $w, int $h, string $format)`	Generate image and return data URI

ImageFormat Enum

All supported formats are defined in Laratusk\PictoMock\Enums\ImageFormat:

Case	Value	MIME Type	Requires GD
`ImageFormat::SVG`	`svg`	`image/svg+xml`	No
`ImageFormat::PNG`	`png`	`image/png`	Yes
`ImageFormat::JPG`	`jpg`	`image/jpeg`	Yes
`ImageFormat::JPEG`	`jpeg`	`image/jpeg`	Yes
`ImageFormat::GIF`	`gif`	`image/gif`	Yes
`ImageFormat::WEBP`	`webp`	`image/webp`	Yes
`ImageFormat::WBMP`	`wbmp`	`image/vnd.wap.wbmp`	Yes

Testing

composer install
./vendor/bin/phpunit

Run only unit tests:

./vendor/bin/phpunit --testsuite Unit

Run only integration tests:

./vendor/bin/phpunit --testsuite Integration

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/my-feature)
Write tests for your changes
Ensure all tests pass (./vendor/bin/phpunit)
Follow PSR-12 coding standards
Submit a pull request

Please open an issue before implementing large changes.

License

The MIT License (MIT). See LICENSE for details.

laratusk / pictomock

Maintainers

Package info

Statistics

Security