README

Laravel Avatar Manager is a lightweight, self-hosted Laravel package for managing user avatars - with support for Gravatar-compatible hashes, local storage and easy integration into existing projects.

📖 This README is also available in 🇩🇪 German.

✨ Features

Avatar URLs based on MD5(Email), as with Gravatar
Fallback to default avatars
Seamless integration with the Laravel user model
Local storage of uploaded avatars
API-based avatar upload using email + API key (no login required)
SQLite compatible ✅

🚀 API Avatar Upload Endpoint

The package provides an optional upload endpoint without requiring user registration.

`POST /api/avatars/upload`

Headers:

X-API-KEY: A valid API key defined in config/avatar-manager.php

Body Parameters:

email (string, required) – The email address used to compute the avatar hash
avatar (image, required) – The uploaded avatar image (max 2MB)

Response:

200 OK: Avatar successfully uploaded
401 Unauthorized: Missing or invalid API key
422 Unprocessable Entity: Validation failed (e.g. invalid email or image)
409 Conflict: Upload aborted – user already has an existing profile photo

ℹ️ If a user exists in your system and already has a profile_photo_path set, the API will reject a new avatar upload via the endpoint to avoid unintended overrides.

The uploaded image will be saved to:

storage/app/public/avatars/{md5(email)}.jpg

Configuration

Add one or more API keys to your config:

// config/avatar-manager.php
'api_keys' => [
    env('AVATAR_API_KEY'),
],

And in your .env file:

AVATAR_API_KEY=your-api-key

🛠️ Installation

You can install the package via composer:

composer require mapo-89/laravel-avatar-manager

⚙️ Configuration

php artisan vendor:publish --provider="Mapo89\LaravelAvatarManager\AvatarManagerServiceProvider"
php artisan storage:link

You can also publish specifically:

# Configuration only
php artisan vendor:publish --tag=avatar-manager-config

# Only assets (e.g. standard images, CSS)
php artisan vendor:publish --tag=avatar-manager-assets

Testing

To keep the package flexible and testable, the AvatarManager uses an interface for accessing user data: Mapo89\LaravelAvatarManager\Contracts\UserProviderInterface

For tests, the test user class is bound via TestUserProvider.

Production operation

In the service provider, the package binds the real user class (e.g. App\Models\User) by default:

public function register()
{
 $this->app->bind(
 \Mapo89\LaravelAvatarManager\Contracts\UserProviderInterface::class,
 \Mapo89\LaravelAvatarManager\Services\UserProvider::class
 );
}

The UserProvider class implements the logic to find users via email hash.

Execute tests

The tests can be executed with various commands:

composer test

./vendor/bin/phpunit --testdox --stderr

./vendor/bin/pest

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 info@postler.de instead of using the issue tracker.

mapo-89 / laravel-avatar-manager

Maintainers

Details