Skip to main content

Integration patterns

Dynamic engine selection​

Pick the engine at runtime and keep a local fallback:

use Renfordt\AvatarSmithy\Avatar;

function avatarFor(array|object $user, string $preferred = 'initials'): string
{
    return Avatar::for($user)
        ->try($preferred)
        ->fallbackTo('gradient')
        ->size(200)
        ->generate()
        ->toHtml();
}

Batch generation​

$avatars = [];

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

Local engines make batch generation cheap because they involve no network requests. Avoid remote engines (Gravatar, DiceBear) in tight loops.

Caching​

Generation is deterministic, so results can be cached by a key derived from the engine, seed, size, and options. For raster output, cache the converted bytes rather than re-running conversion per request:

$key = "avatar:{$engine}:{$size}:" . sha1($email);

$png = $cache->remember($key, 86400, function () use ($email, $size) {
    return Avatar::engine('initials')
        ->seed($email)
        ->size($size)
        ->generate()
        ->toPng()
        ->getContent();
});

Serving from a route (Laravel)​

use Renfordt\AvatarSmithy\Avatar;
use Renfordt\AvatarSmithy\Http\AvatarResponder;

Route::get('/avatar/{user}', function (User $user) {
    $avatar = Avatar::for($user)
        ->try('gravatar')
        ->fallbackTo('initials')
        ->fallbackTo('gradient')
        ->size(400)
        ->generate();

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

See HTTP responses for download and PSR-7 variants.

Logging declined engines​

Attach a PSR-3 logger to see which engines decline or fail within a chain that still succeeds:

$builder = (new \Renfordt\AvatarSmithy\AvatarBuilder('gravatar'))
    ->setLogger($logger)
    ->fallbackTo('initials');

$avatar = $builder->seed($email)->name($name)->generate();