README

🚀 A lightweight Laravel package that adds avatars to your Eloquent models. It builds avatar URLs from Gravatar, DiceBear, UI Avatars, Boring Avatars, Vercel Avatar, RoboHash or Unavatar, and you can plug in your own.

Warning

v2.0 is a breaking release. It requires PHP 8.2+ and Laravel 12+, and the driver API, config file, and exceptions have changed. If you use v1, read Upgrading from v1 before you update.

Supported Avatar Drivers

Driver	Config key	Style	Identifier
Gravatar	`gravatar`	The user's own Gravatar, with a generated fallback	Email
DiceBear	`dicebear`	31 illustrated styles (API 10.x)	Any string
UI Avatars	`ui-avatars`	Initials on a colored background	Name
Boring Avatars	`boringavatar`	Abstract SVG shapes	Any string
Vercel Avatar	`vercel`	Gradients	Any string
RoboHash	`robohash`	Robots, monsters, cats, and more	Any string
Unavatar	`unavatar`	The user's real avatar from 99 social and email providers	Email, username, or domain

Note

Unavatar allows 25 anonymous requests per day per IP address, and its free plans require attribution. The default Boring Avatars URL points to a free community deployment. The official API is a paid service with its own domain, which you set with the base_url option. The colors option uses the free endpoint's format and is untested against the paid API.

Installation

This package requires PHP 8.2+ and Laravel 12 or 13. Laravel 11 is not supported because every 11.x release has an unpatched security advisory.

composer require martian/laravatar

Laravel discovers the service provider and the Laravatar facade automatically.

Upgrading from v1

v1 stays available for Laravel 10. To stay on it, pin "martian/laravatar": "^1.0".

To upgrade, follow these steps:

Update the package:
```
composer require martian/laravatar:^2.0
```
Replace your published config file. The class and options keys are gone, and each driver's options now sit directly under its name.
```
php artisan vendor:publish --tag=laravatar-config --force
```
Copy your old values into the new file. The LARAVATAR_DRIVER values are unchanged. The Boring Avatars squared option is now square.

Update direct driver calls. The identifier now goes to url(), and option methods drop the set prefix. Each option method returns a new instance, so chain the calls or reassign the result.

// v1
$avatar = new DiceBear('Jane Doe');
$avatar->setStyle('lorelei');
$avatar->setSize(100);
$url = $avatar->getUrl();

// v2
$url = Laravatar::driver('dicebear')->style('lorelei')->size(100)->url('Jane Doe');

v1	v2
`setSize()`, `setFormat()`, `setStyle()`, `setVariant()`	`size()`, `format()`, `style()`, `variant()`
`BoringAvatar::setSquared()`, `setColors('a,b')`	`square()`, `colors(['a', 'b'])`
`UiAvatars::setBackground()`, `setColor()`, `setRounded()`	`background()`, `color()`, `rounded()`
`new Laravatar($value)->getUrl()`	`Laravatar::url($value)`
`LaravatarFacade`	`AmplifiedHQ\Laravatar\Facades\Laravatar`

Update exception handling. InvalidSizeException, InvalidFormatException, InvalidStyleException, InvalidVariantException, MissingPropertyException, and UnsupportedDriverException are removed. Catch AmplifiedHQ\Laravatar\Exceptions\InvalidOptionException for bad options. An unknown driver throws InvalidArgumentException.
Replace removed helpers. The generate_color() and hex2rgba() global functions are removed. HasAvatar::generateAndSaveAvatar() is removed; use getAvatarUrl().

Important

v2 does not change avatar URLs already stored in your database. v1 stored DiceBear URLs that use API 7.x, which DiceBear shuts down on April 30, 2028. To regenerate them, run this once. It also replaces avatars your users uploaded, so narrow the query if you store those in the same column.

User::each(fn (User $user) => $user->update(['avatar' => $user->getAvatarUrl()]));

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=laravatar-config

Set the default driver in .env:

LARAVATAR_DRIVER=dicebear

Each driver's options are listed in config/laravatar.php. Options that take a fixed set of values have an enum in AmplifiedHQ\Laravatar\Enums.

'dicebear' => [
    'style' => 'avataaars',
    'format' => 'svg',
    'size' => 96,
    'radius' => 0,
    'version' => '10.x',
    'base_url' => 'https://api.dicebear.com',
],

Usage

Using the `HasAvatar` trait

Add the trait to your model. When the model is created, it stores an avatar URL in the avatar column. It does not overwrite an avatar that was set explicitly, and it leaves the column empty when the source column is blank.

namespace App\Models;

use AmplifiedHQ\Laravatar\HasAvatar;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasAvatar;

    /** Column the avatar is generated from. Defaults to "email". */
    protected $avatarColumn = 'email';

    /** Column the avatar URL is stored in. Defaults to "avatar". */
    protected $avatarStorageColumn = 'avatar';

    /** Driver for this model. Defaults to the configured default driver. */
    protected $avatarDriver = 'gravatar';
}

To fill avatars for existing rows, call getAvatarUrl():

User::whereNull('avatar')->lazyById()->each(fn (User $user) => $user->update(['avatar' => $user->getAvatarUrl()]));

Important

Gravatar and Unavatar look up a real user, so use the email column with them. The other drivers accept any string column, such as name or username.

Using the facade

Laravatar::url() uses the default driver. Laravatar::driver() selects another driver. Option methods return a new instance, so the configured driver is never changed.

use AmplifiedHQ\Laravatar\Enums\DiceBearStyle;
use AmplifiedHQ\Laravatar\Facades\Laravatar;

Laravatar::url('jane@example.com');
// https://www.gravatar.com/avatar/8c87b489ce35cf2e2f39f80e282cb2e804932a56a213983eeeb428407d43b52d?s=96&d=mp&r=g

Laravatar::driver('dicebear')->style(DiceBearStyle::Lorelei)->size(128)->url('Jane Doe');
// https://api.dicebear.com/10.x/lorelei/svg?seed=Jane%20Doe&size=128

Laravatar::driver('ui-avatars')->background('1a237e')->color('ffffff')->rounded()->url('Jane Doe');
// https://ui-avatars.com/api/?name=Jane%20Doe&size=96&format=png&background=1a237e&color=ffffff&rounded=true&bold=false

Laravatar::driver('boringavatar')->variant('beam')->square()->colors(['264653', '2a9d8f'])->url('Jane Doe');
// https://boring-avatars-api.vercel.app/api/avatar?name=Jane%20Doe&variant=beam&size=96&square=true&colors=%23264653&colors=%232a9d8f

Laravatar::driver('robohash')->set('set4')->url('Jane Doe');
// https://robohash.org/Jane%20Doe.png?set=set4&size=96x96

Laravatar::driver('unavatar')->source('github')->url('hendurhance');
// https://unavatar.io/github/hendurhance

You can also create a driver directly, for example (new Gravatar(size: 200))->url('jane@example.com').

Invalid options throw AmplifiedHQ\Laravatar\Exceptions\InvalidOptionException.

Custom drivers

Implement AmplifiedHQ\Laravatar\Contracts\AvatarInterface and register the driver in a service provider:

use AmplifiedHQ\Laravatar\Facades\Laravatar;

Laravatar::extend('cdn', fn ($app) => new CdnAvatar(config('services.cdn.url')));

Then set LARAVATAR_DRIVER=cdn, or call Laravatar::driver('cdn').

Testing

composer test          # unit and feature tests
composer test:network  # checks every provider's live API
composer analyse       # PHPStan

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email hendurhance.dev@gmail.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

martian / laravatar

Package info

Security

Statistics

README

Supported Avatar Drivers

Installation

Upgrading from v1

Configuration

Usage

Using the `HasAvatar` trait

Using the facade

Custom drivers

Testing

Changelog

Contributing

Security

Credits

License

martian / laravatar

Package info

Security

Statistics

README

Supported Avatar Drivers

Installation

Upgrading from v1

Configuration

Usage

Using the HasAvatar trait

Using the facade

Custom drivers

Testing

Changelog

Contributing

Security

Credits

License

Using the `HasAvatar` trait