Pixelo — Laravel Avatar Generator

Generate dynamic, colorful profile placeholder images from any name string.
No external services, no heavy dependencies — just PHP's built-in GD extension.

---

Features

• 🎨 Deterministic colors — same name always maps to the same color
• 🔤 Smart initials — extracts 1–4 initials from any name string
• 🔵 Three shapes — circle, square, rounded
• 📐 Any size — 16 px to 1024 px
• 🌐 HTTP route — use as a plain <img src> URL
• 🖼️ Blade directives — @pixeloAvatar, @pixeloUrl
• ⚡ ETag caching — proper Cache-Control + ETag headers
• 🎨 Full color control — override background + foreground per call
• 🧩 Custom palette — swap the default 18-color palette in config
• 0️⃣ Zero extra dependencies — GD only

---

Requirements

PHP	^8.0
Laravel	^10, ^11, ^12
ext-gd	*

---

Installation

composer require jackson/pixelo

Laravel's package auto-discovery registers the service provider and Pixelo facade automatically.

Publish the config (optional):

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

---

Usage

Facade

use pixelo\Facades\Pixelo;

// Embed in <img src>
$dataUri = Pixelo::make('Jackson Konjengbam')->toBase64();

// Laravel HTTP response (for controller actions)
return Pixelo::make('Jane Smith')->size(256)->shape('rounded')->toResponse();

// Save PNG to disk
Pixelo::make('Alice')->save(storage_path('app/public/avatars/alice.png'));

// Route URL via facade
$url = Pixelo::make('Bob')->url('Bob', ['size' => 64, 'shape' => 'circle']);

// Full chain — all options
$png = Pixelo::make('Bob')
    ->size(200)
    ->shape('circle')
    ->background('#1E88E5')
    ->color('#FFFFFF')
    ->fontSize(0.45)    // font size as fraction of image size
    ->bold(true)
    ->length(2)
    ->toPng();

Helper functions

// Returns a data URI
$src = pixelo('Jackson Konjengbam');

// With options
$src = pixelo('Jane Smith', [
    'size'   => 64,
    'shape'  => 'rounded',
    'bg'     => '5E35B1',     // hex without #
    'fg'     => 'FFFFFF',
    'length' => 2,
    'bold'   => false,
]);

// Returns a route URL
$url = pixelo_url('Jackson Konjengbam', ['size' => 128, 'shape' => 'circle']);

Blade templates

{{-- Data URI (inline, no HTTP request) --}}
<img src="{{ pixelo('Jackson Konjengbam') }}" width="64" height="64" alt="JD">

{{-- Blade directive --}}
<img src="@pixeloAvatar('Jackson Konjengbam')" width="64" alt="JD">
<img src="@pixeloAvatar('Jane', ['size' => 96, 'shape' => 'rounded'])" width="96" alt="J">

{{-- Route URL --}}
<img src="@pixeloUrl('Jackson Konjengbam')" width="64" alt="JD">
<img src="{{ pixelo_url('Jane Smith', ['size' => 128]) }}" width="128">

HTTP endpoint

GET /pixelo/avatar?name=Jackson+Konjengbam
GET /pixelo/avatar?name=Jane+Smith&size=256&shape=rounded
GET /pixelo/avatar?name=Bob&size=64&shape=square&bg=1E88E5&fg=FFFFFF
GET /pixelo/avatar?name=Alice&size=128&length=1

Query parameters:

Parameter	Type	Default	Description
name	string	?	Name to extract initials from
size	integer	128	Image size in pixels (16–1024)
shape	string	circle	circle, square, or rounded
bg	string	auto	Background hex (without #)
fg	string	auto	Foreground/text hex (without #)
length	integer	2	Number of initials to render (1–4)

---

API Reference

All methods on AvatarGenerator are fluent (chainable). make() returns a fresh clone so the base instance is never mutated.

Builder methods

Method	Signature	Description
make	make(string $name): static	Set the name to generate initials from. Always call this first.
size	size(int $size): static	Image width/height in pixels. Clamped to 16–1024.
shape	shape(string $shape): static	'circle', 'square', or 'rounded'. Throws on invalid value.
background	background(string $color): static	Background hex color (with or without #).
color	color(string $color): static	Foreground/text hex color (with or without #).
fontSize	fontSize(float $ratio): static	Font size as a fraction of image size (0.1–0.9). Default: 0.40.
bold	bold(bool $bold = true): static	Whether to use a bold font weight. Default: true.
length	length(int $length): static	Number of initials to render (1–4). Default: 2.

Output methods

Method	Returns	Description
toPng()	string	Raw PNG binary.
toBase64()	string	Data URI: data:image/png;base64,… — embed directly in <img src>.
toResponse()	Illuminate\Http\Response	Laravel HTTP response with Content-Type: image/png and caching headers.
save(string $path)	string	Write PNG to disk, returns the path.
url(string $name, array $options = [])	string	Build a URL to the built-in pixelo.avatar route.

---

Configuration

config/pixelo.php after publishing:

return [
    'size'         => 128,
    'shape'        => 'circle',      // circle | square | rounded
    'length'       => 2,
    'font_ratio'   => 0.40,          // font size as fraction of image size
    'bold'         => true,
    'route_prefix' => 'pixelo/avatar',

    // Override the color palette — [background_hex, foreground_hex]
    'palette' => null,
    // Example:
    // 'palette' => [
    //     ['#0F172A', '#38BDF8'],
    //     ['#064E3B', '#6EE7B7'],
    // ],
];

---

Custom font

Drop any .ttf file into src/Fonts/ and name it Roboto-Bold.ttf (or NotoSans-Bold.ttf).
Pixelo picks it up automatically. Without a custom font it falls back to GD's built-in bitmap font.

---

Patterns

User model accessor

// app/Models/User.php
public function getAvatarAttribute(): string
{
    return pixelo($this->name, ['size' => 128]);
}

API resource

// app/Http/Resources/UserResource.php
'avatar' => pixelo_url($this->name, ['size' => 64, 'shape' => 'circle']),

Consistent per-user avatars (no storage)

The color selection is purely deterministic — nameToIndex() hashes the name string to a stable palette index. The same name input always produces identical output. No database column or file storage needed.

---

Running Tests

composer install
vendor/bin/phpunit

---

License

MIT © Jackson K