README

Change the default avatar URL provider for Filament to one from Boring Avatars.

Notice

This package is made for Filament v2. This package doesn't support Filament v3.

For Filament v3, see the Boring Avatars implementation and setup of a different avatar provider in the Filament v3 Docs.

Why choose this plugin?

Boring avatars is a tiny JavaScript React library that generates custom, SVG-based avatars from any username and color palette.

This plugin uses the Boring Avatar API to get generated user avatars. Only the initials of the Filament User's name are submitted to the API.

Installation

You can install the package via composer:

composer require cmdinglasan/filament-boring-avatars

You can publish the config file with:

php artisan vendor:publish --tag="filament-boring-avatars-config"

This is the contents of the published config file:

return [
    // default source url for Boring Avatars API
    'url' => 'https://source.boringavatars.com',

    // variants = marble (default), beam, pixel, sunset, ring, bauhaus
    'variant' => 'marble',

    // size in px
    'size' => '40',

    // array of colors to use
    'colors' => ['#264653','#2a9d8f','#e9c46a','#f4a261','#e76f51'],
];

How to use

1. In Filament

Inside the Filament config.php file, change the avatar_url_provider to Cmdinglasan\FilamentBoringAvatars\AvatarProviders\UiAvatarsProvider::class.

/*
|--------------------------------------------------------------------------
| Default Avatar Provider
|--------------------------------------------------------------------------
|
| This is the service that will be used to retrieve default avatars if one
| has not been uploaded.
|
*/

'default_avatar_provider' => Cmdinglasan\FilamentBoringAvatars\AvatarProviders\UiAvatarsProvider::class,

2. Inside your own Laravel app

To use this inside your Laravel app, just add the HasAvatarUrl trait to your models.

<?php

namespace App\Models;

use Cmdinglasan\FilamentBoringAvatars\Traits\HasAvatarUrl;

class User
{
    use HasAvatarUrl;
}

In the model, use the model's name attribute or add a name attribute.

// Example for getAttribute:
public function getNameAttribute()
{
    return $this->first_name . ' ' . $this->last_name;
}

// Example using accessor
use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * Get the user's name
     *
     * @return Attribute
     */
    protected function name(): Attribute
    {
        return Attribute::make(
            get: fn () => $this->first_name . ' ' . $this->last_name,
        );
    }
}

Then just call it using the avatarUrl property.

$user = User::find(1)->avatarUrl;

Testing

This package uses PestPHP for testing. To run the tests, run the following command:

composer test

cmdinglasan / filament-boring-avatars

Maintainers

Details