Avatars

Description

Avatars is Laravel Enso's user avatar package.

It attaches one avatar record to each user, exposes authenticated endpoints for viewing, uploading, and regenerating avatars, and integrates with Enso's file pipeline so custom uploads are stored and transformed consistently.

The package also generates default avatars automatically. It prefers Gravatar when a public image exists for the user's email address and falls back to a locally generated Laravolt avatar when it does not.

The frontend integration lives primarily in the Enso user profile experience and reusable avatar components from @enso-ui/users.

Installation

This package comes pre-installed in Laravel Enso applications that support user profile avatars.

For standalone installation in an Enso-based application:

composer require laravel-enso/avatars

The package auto-registers its service providers, loads migrations, registers API routes, observes user creation, and exposes the avatar generation command.

Run the migrations after installation:

php artisan migrate

If you need the package storage scaffolding, publish it with:

php artisan vendor:publish --tag=avatars-storage

Features

Adds a one-to-one avatar relation to LaravelEnso\Users\Models\User through dynamic methods.
Adds a generateAvatar() dynamic method to users for regenerating their default avatar.
Generates a default avatar automatically whenever a new user is created.
Prefers Gravatar and falls back to a generated Laravolt image when no Gravatar exists.
Stores uploaded avatar files through laravel-enso/files.
Deletes the previously attached file when an avatar is replaced.
Enforces square image uploads.
Exposes avatar display, upload, and regenerate endpoints under the core API namespace.
Registers permissions and authorization for avatar operations.

Usage

The package binds an avatar() relation and generateAvatar() method to the Enso user model:

$user->avatar;
$user->generateAvatar();

Store a custom uploaded avatar for the authenticated user:

use Illuminate\Http\UploadedFile;

$request->validate([
    'avatar' => 'required|image:allow_svg|dimensions:ratio=1',
]);

$request->user()->avatar->store(
    UploadedFile::fake()->image('avatar.png', 512, 512),
);

Regenerate the default avatar:

$request->user()->generateAvatar();

Display an avatar in the browser by hitting the show endpoint:

route('core.avatars.show', $user->avatar->id);

Note

The package is designed to work with a single avatar per user. When you regenerate or upload a new avatar, the previously attached file is removed automatically.