Skip to main content

Quick start

Generate from a seed​

Avatar::engine() selects the primary engine. seed() provides the value used to derive the avatar; name() supplies the display name used by the initials engine and for alt text.

use Renfordt\AvatarSmithy\Avatar;

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

echo $avatar->toHtml();

If no seed is set, the engine falls back to the name as its seed. If neither is set, an empty string is used.

Generate from a user​

Avatar::for() extracts the seed and name from an object or array, so you do not have to wire them up manually.

// Object with public properties or getEmail()/getName() methods
$avatar = Avatar::for($user)
    ->try('initials')
    ->size(300)
    ->generate();

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

For objects, a getEmail()/getName() method takes precedence over a matching email/name property when both are present. The email is used as the seed.

Add a fallback chain​

fallbackTo() appends an engine that is tried if the previous one fails or declines. List a local engine last so generation always succeeds.

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

See Fallback chains for the exact semantics.

Output​

generate() returns a GeneratedAvatar. Convert it to the form you need:

$avatar->toHtml();      // <img> tag (SVG embedded as a base64 data URI)
$avatar->toBase64();    // data: URI
$avatar->toUrl();       // remote URL when available, otherwise a data URI
$avatar->getContent();  // raw SVG markup, binary data, data URI, or URL
$avatar->save('/path/to/avatar.svg');

See Output formats for the full list.