PHPackages                             renfordt/avatar-smithy - 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. renfordt/avatar-smithy

ActiveLibrary

renfordt/avatar-smithy
======================

A modern PHP package that bundles multiple avatar generation engines. Forge beautiful avatars with ease.

00[1 PRs](https://github.com/renfordt/AvatarSmithy/pulls)PHPCI passing

Since Dec 1Pushed 4mo agoCompare

[ Source](https://github.com/renfordt/AvatarSmithy)[ Packagist](https://packagist.org/packages/renfordt/avatar-smithy)[ RSS](/packages/renfordt-avatar-smithy/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (2)Used By (0)

[![Preview Image](preview.png "AvatarSmithy Preview")](preview.png)

AvatarSmithy
============

[](#avatarsmithy)

**Forge beautiful avatars with ease.**

[![PHP Version](https://camo.githubusercontent.com/42e9da7915dbb5d727afb84ac5e1432293993bbe7c6e20127e01bce96d1520a5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e342b2d3737374242343f7374796c653d666c61742d737175617265266c6f676f3d706870)](https://www.php.net)[![License](https://camo.githubusercontent.com/152aa2a37725b9fd554b28ff24d270f6071c67927a63e6d635a55c8e188e20c7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e3f7374796c653d666c61742d737175617265)](LICENSE)[![PRs Welcome](https://camo.githubusercontent.com/25b3e6d0d42c98de74a98cbb4d149a1c09020cf6d1361993b72d7d5b8ffed363/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5052732d77656c636f6d652d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](CONTRIBUTING.md)

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) • [Examples](#advanced-examples) • [Contributing](CONTRIBUTING.md)

---

✨ Features
----------

[](#-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
--------------

[](#-requirements)

- PHP 8.4 or higher
- GD extension
- Composer

📦 Installation
--------------

[](#-installation)

Install via Composer:

```
composer require renfordt/avatar-smithy
```

🚀 Quick Start
-------------

[](#-quick-start)

### Basic Usage

[](#basic-usage)

Generate an avatar with just a few lines:

```
use Renfordt\AvatarSmithy\Avatar;

// Simple avatar with email seed
$avatar = Avatar::engine('initials')
    ->seed('john.doe@example.com')
    ->name('John Doe')
    ->generate();

echo $avatar; // Outputs HTML img tag
```

### Smart User Factory

[](#smart-user-factory)

Automatically extract email and name from user objects or arrays:

```
// Works with objects
$user = new User(['email' => 'jane@example.com', 'name' => 'Jane Smith']);
$avatar = Avatar::for($user)
    ->try('initials')
    ->size(300)
    ->generate();

// Works with arrays
$userData = ['email' => 'bob@example.com', 'name' => 'Bob Wilson'];
$avatar = Avatar::for($userData)
    ->try('gravatar')
    ->fallbackTo('initials')
    ->generate();
```

### Fallback Chain

[](#fallback-chain)

Create a robust avatar system with automatic fallbacks:

```
$avatar = Avatar::engine('gravatar')
    ->fallbackTo('dicebear')
    ->fallbackTo('initials')  // Final fallback always succeeds
    ->seed('user@example.com')
    ->name('User Name')
    ->size(256)
    ->generate();
```

🎨 Available Engines
-------------------

[](#-available-engines)

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

[](#-output-formats)

AvatarSmithy provides multiple output formats for maximum flexibility:

### HTML Image Tag

[](#html-image-tag)

```
$avatar->toHtml();
//
```

### Base64 Data URI

[](#base64-data-uri)

```
$avatar->toBase64();
// data:image/svg+xml;base64,
// PHN2ZyB3aWR0aD0iMjAwIi...
```

### URL or Raw Content

[](#url-or-raw-content)

```
$avatar->toUrl();
// Gravatar: https://gravatar.com/...
// Local: data:image/svg+xml;base64,...
```

### PSR-7 HTTP Response

[](#psr-7-http-response)

```
// In a Laravel/Symfony controller
return Avatar::for($user)
    ->try('gravatar')
    ->fallbackTo('initials')
    ->toResponse();
```

### Direct String Conversion

[](#direct-string-conversion)

```
echo $avatar;
// Auto-converts to HTML img tag
```

### Save to File

[](#save-to-file)

```
$avatar->save('/path/to/avatar.svg');
// Saves avatar to filesystem
```

⚙️ Configuration Options
------------------------

[](#️-configuration-options)

### Universal Options

[](#universal-options)

These options work across all engines:

```
Avatar::engine('initials')
    ->seed('unique-identifier')      // Seed for deterministic generation
    ->name('John Doe')                // User's display name
    ->size(200)                       // Avatar size in pixels (default: 200)
    ->generate();
```

### Engine-Specific Options

[](#engine-specific-options)

**Initials Engine**```
Avatar::engine('initials')
    ->name('John Doe')
    ->size(256)
    ->shape('circle')                 // 'circle' or 'square'
    ->bold(true)                      // Bold font weight
    ->fontSize(100)                   // Custom font size
    ->backgroundColor(['#FF6B6B', '#4ECDC4', '#45B7D1'])  // Color palette
    ->generate();
```

**Gravatar Engine**```
Avatar::engine('gravatar')
    ->seed('user@example.com')        // Email address
    ->size(256)
    ->defaultImage('identicon')       // '404', 'mp', 'identicon', 'monsterid',
                                      // 'wavatar', 'retro', 'robohash', 'blank'
    ->rating('g')                     // 'g', 'pg', 'r', 'x'
    ->generate();
```

**DiceBear Engine**```
Avatar::engine('dicebear')
    ->seed('user@example.com')
    ->size(256)
    ->style('avataaars')              // DiceBear style (e.g., 'avataaars', 'bottts')
    ->backgroundColor('#FF6B6B')      // Hex color
    ->radius(10)                      // Border radius
    ->generate();
```

**Pixel Engines**```
// Single color pixel
Avatar::engine('pixel')
    ->seed('user@example.com')
    ->size(256)
    ->pixels(5)                       // Grid size (5x5 pixels)
    ->symmetry(true)                  // Mirror horizontally
    ->foregroundLightness(0.4)        // Lightness of colored pixels (0.0-1.0)
    ->backgroundLightness(0.9)        // Lightness of background (0.0-1.0)
    ->generate();

// Multi-color pixel
Avatar::engine('multicolor-pixel')
    ->seed('user@example.com')
    ->size(256)
    ->pixels(6)
    ->symmetry(true)
    ->numColors(4)                    // Number of colors in palette
    ->backgroundLightness(0.95)
    ->generate();
```

**Bauhaus Engine**```
Avatar::engine('bauhaus')
    ->seed('user@example.com')
    ->size(256)
    ->numShapes(5)                    // Number of geometric shapes
    ->numColors(3)                    // Color palette size
    ->fillAll(false)                  // Whether to fill entire canvas
    ->generate();
```

**Gradient Engine**```
Avatar::engine('gradient')
    ->seed('user@example.com')
    ->size(256)
    ->gradientType('linear')          // 'linear' or 'radial'
    ->colorStops(3)                   // Number of color stops
    ->generate();
```

💎 Advanced Examples
-------------------

[](#-advanced-examples)

### Laravel Integration

[](#laravel-integration)

```
// routes/web.php
Route::get('/avatar/{user}', function (User $user) {
    return Avatar::for($user)
        ->try('gravatar')
        ->fallbackTo('initials')
        ->size(400)
        ->toResponse();
});

// In a Blade template

```

### Custom Styling with Fallback Chain

[](#custom-styling-with-fallback-chain)

```
$avatar = Avatar::for($user)
    ->try('gravatar')
    ->fallbackTo('dicebear')
    ->fallbackTo('initials')
    ->size(300)
    ->defaultImage('404')             // Gravatar: fail if not found
    ->style('avataaars')              // DiceBear: cartoon style
    ->shape('circle')                 // Initials: circular shape
    ->bold(true)                      // Initials: bold text
    ->generate();
```

### Batch Generation

[](#batch-generation)

```
$users = User::all();
$avatars = [];

foreach ($users as $user) {
    $avatars[$user->id] = Avatar::for($user)
        ->try('initials')
        ->size(150)
        ->generate()
        ->toBase64();
}
```

### Dynamic Engine Selection

[](#dynamic-engine-selection)

```
function generateAvatar(array $user, string $preferredEngine = 'initials'): string
{
    return Avatar::for($user)
        ->try($preferredEngine)
        ->fallbackTo('initials')
        ->size(200)
        ->generate()
        ->toHtml();
}

// Usage
echo generateAvatar($user, 'pixel');
echo generateAvatar($adminUser, 'gravatar');
```

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on:

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

📄 License
---------

[](#-license)

This package is open-source software licensed under the [MIT license](LICENSE).

🙏 Credits
---------

[](#-credits)

**Created by** [renfordt](https://github.com/renfordt)

**Built with:**

- [meyfa/php-svg](https://github.com/meyfa/php-svg) — SVG generation
- [renfordt/colors](https://github.com/renfordt/colors) — Color manipulation
- [renfordt/clamp](https://github.com/renfordt/clamp) — Value clamping

---

**⚒️ Forge beautiful avatars with AvatarSmithy ⚒️**

[⬆ Back to Top](#avatarsmithy)

###  Health Score

18

—

LowBetter than 8% of packages

Maintenance50

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity15

Early-stage or recently created project

 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/1edb79f2a1fcd61016ec9a5b65183e1f6e7852a4b1f9a5bd6f69c6160366f22c?d=identicon)[renfordt](/maintainers/renfordt)

---

Top Contributors

[![renfordt](https://avatars.githubusercontent.com/u/699163?v=4)](https://github.com/renfordt "renfordt (28 commits)")

### Embed Badge

![Health badge](/badges/renfordt-avatar-smithy/health.svg)

```
[![Health](https://phpackages.com/badges/renfordt-avatar-smithy/health.svg)](https://phpackages.com/packages/renfordt-avatar-smithy)
```

PHPackages © 2026

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