Skip to main content

AvatarSmithy

AvatarSmithy is a PHP library for generating avatars. It exposes a single fluent builder that wraps seven interchangeable generation engines and a configurable fallback chain. Engines either render an image locally (SVG) or fetch one from an external service.

The library is framework-agnostic. It works standalone and integrates with Laravel or Symfony through a small HTTP responder helper.

Requirements​

  • PHP 8.4 or higher
  • The gd extension (required; used for raster conversion and as the SVG rasterization backend)
  • Composer
  • The imagick extension is optional. When present it is preferred over gd for PNG/JPG/WebP conversion.

Concepts​

A generation request moves through three objects:

  1. Avatar — a static factory. Avatar::engine() starts a builder with a named primary engine; Avatar::for() starts a builder and pre-fills the seed and name from a user object or array.
  2. AvatarBuilder — collects the seed, name, size, and engine-specific options, then runs the engine chain when generate() is called.
  3. GeneratedAvatar — wraps the produced content (SVG markup, binary image data, a data URI, or a URL) and converts it to the format you need.

Generation is deterministic: the same seed always produces the same avatar for a given engine and option set. Colors and layout are derived from an MD5 hash of the seed (or name).

Example​

use Renfordt\AvatarSmithy\Avatar;

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

echo $avatar->toHtml();

Continue with Installation and the Quick start.