renfordt / avatar-smithy

dev-main 2026-07-30 21:06 UTC

Requires

• php: ^8.4
• ext-gd: *
• psr/log: ^3.0
• renfordt/clamp: ^1.1
• renfordt/colors: ^2.0
• renfordt/php-svg: ^0.1.0

Requires (Dev)

• laravel/pint: ^1.29
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.2
• phpstan/phpstan-phpunit: ^2.0
• phpunit/phpunit: ^13.1
• rector/rector: ^2.4
• symfony/var-dumper: ^8.1

Suggests

• imagick/imagick: For better image encoding support

MIT

• renfordt

• gravatar
• php
• avatar
• svg
• bauhaus
• gradient
• fallback
• Initials
• avatar-generator
• DiceBear
• image-generation
• profile-picture
• pixel-art

Published on Packagist.org on 2026-08-08 08:07 UTC

README

 # AvatarSmithy **Forge beautiful avatars with ease.** [](https://codeberg.org/renfordt/AvatarSmithy) [](https://packagist.org/packages/renfordt/avatar-smithy/)  [](https://ci.renfordt.dev/repos/5) [](https://sonar.renfordt.dev/dashboard?id=AvatarSmithy) [](https://sonar.renfordt.dev/dashboard?id=AvatarSmithy) A modern PHP library that bundles **7 avatar generation engines** into a unified, fluent API. Create stunning avatars from user data with automatic fallback support and extensive customization. [Installation](#installation) • [Quick Start](#quick-start) • [Engines](#available-engines) • [Contributing](CONTRIBUTING.md)

Features

• 7 Built-in Engines — From SVG initials to pixel art, Gravatar integration, and more
• Fluent API — Intuitive builder pattern for effortless configuration
• Smart Fallback — Automatic failover between engines ensures reliability
• Flexible Output — Export as HTML, Base64, URLs, PSR-7 responses, or stream directly
• Highly Customizable — Extensive styling options for each engine
• Framework Agnostic — Works standalone or integrates seamlessly with Laravel/Symfony
• Type Safe — Built with strict types and PHPStan level max
• Modern PHP — Requires PHP 8.4+ with latest language features

Requirements

• PHP 8.4 or higher
• GD extension
• Composer

Installation

Install via Composer:

composer require renfordt/avatar-smithy

Quick Start

Basic Usage

Generate an avatar with just a few lines:

use Renfordt\AvatarSmithy\Avatar;

// Simple avatar with email seed
$avatar = Avatar::engine('initials')
    ->seed('[e-mail]')
    ->name('John Doe')
    ->generate();

echo $avatar; // Outputs HTML img tag

Smart User Factory

Automatically extract email and name from user objects or arrays:

// Works with objects
$user = new User(['email' => '[e-mail]', 'name' => 'Jane Smith']);
$avatar = Avatar::for($user)
    ->try('initials')
    ->size(300)
    ->generate();

// Works with arrays
$userData = ['email' => '[e-mail]', 'name' => 'Bob Wilson'];
$avatar = Avatar::for($userData)
    ->try('gravatar')
    ->fallbackTo('initials')
    ->generate();

Available Engines

Engine	Description	Network	Example Use Case
initials	SVG avatars with user initials in colored shapes	❌	Default user profiles
gravatar	Fetches from Gravatar.com based on email hash	✅	Blog comments, social platforms
dicebear	Fetches from DiceBear API (various styles)	✅	Fun, cartoon-style avatars
pixel	Generates retro pixel-art style avatars	❌	Gaming platforms, retro themes
multicolor-pixel	Multi-colored variant of pixel engine	❌	Vibrant pixel art avatars
bauhaus	Bauhaus-inspired geometric art avatars	❌	Modern, artistic profiles
gradient	Beautiful gradient-based avatars	❌	Minimalist, colorful designs

[!TIP] Engines marked with ❌ generate avatars locally without network requests, while ✅ engines fetch from external APIs.

Output Formats

AvatarSmithy provides multiple output formats for maximum flexibility. Pick the method that matches where the avatar needs to go:

echo $avatar;                           // Auto-converts to an HTML <img> tag
$avatar->toHtml();                      // <img src="data:image/svg+xml;base64,..." alt="Avatar">
$avatar->toBase64();                    // data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjAwIi...
$avatar->toUrl();                       // Gravatar: https://gravatar.com/... | Local:    data:image/svg+xml;base64,...
$avatar->save('/path/to/avatar.svg');   // Writes the avatar to the filesystem

// In a Laravel/Symfony controller
use Renfordt\AvatarSmithy\Http\AvatarResponder;

$avatar = Avatar::for($user)
    ->try('gravatar')
    ->fallbackTo('initials')
    ->generate();

return (new AvatarResponder($avatar))->toResponse();

[!TIP] Need a PSR-7 response? Build one from $avatar->getContent() and $avatar->getContentType() using your framework's PSR-17 factory.

Documentation

You can find the full documentation on this page: Documentation

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details on:

• Development setup and testing
• Code quality standards
• Architecture overview
• Creating custom engines
• Pull request process

License

This package is open-source software licensed under the MIT license.

Credits

Built with:

• meyfa/php-svg — SVG generation
• renfordt/colors — Color manipulation
• renfordt/clamp — Value clamping