PHPackages mapo-89/laravel-avatar-manager - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. mapo-89/laravel-avatar-manager ActiveLibrary[Utility & Helpers](/categories/utility) mapo-89/laravel-avatar-manager ============================== Simple Laravel package to serve avatars by email hash v1.2.1(9mo ago)018MITPHPPHP ^8.2CI passing Since Jun 15Pushed 9mo agoCompare [ Source](https://github.com/mapo-89/laravel-avatar-manager)[ Packagist](https://packagist.org/packages/mapo-89/laravel-avatar-manager)[ Docs](https://github.com/mapo-89/laravel-avatar-manager)[ RSS](/packages/mapo-89-laravel-avatar-manager/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (4)Dependencies (4)Versions (6)Used By (0) Laravel Avatar Manager ====================== [](#laravel-avatar-manager) [![Latest Version on Packagist](https://camo.githubusercontent.com/122cfc05e2c192e7307a52b4b8b8c1a238b2d45d1b4f0fc3f7436e865fd262f8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d61706f2d38392f6c61726176656c2d6176617461722d6d616e616765722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mapo-89/laravel-avatar-manager)[![Total Downloads](https://camo.githubusercontent.com/c2de3ae4b353e4e2274fe2ee5a52d7376baf6bc0d2c3dfec227861ac695ecd35/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d61706f2d38392f6c61726176656c2d6176617461722d6d616e616765722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/mapo-89/laravel-avatar-manager)[![GitHub Actions](https://github.com/mapo-89/laravel-avatar-manager/actions/workflows/main.yml/badge.svg)](https://github.com/mapo-89/laravel-avatar-manager/actions/workflows/main.yml/badge.svg)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](LICENSE) **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](README.de.md). --- ✨ Features ---------- [](#-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 ---------------------------- [](#-api-avatar-upload-endpoint) The package provides an optional upload endpoint without requiring user registration. ### `POST /api/avatars/upload` [](#post-apiavatarsupload) **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 [](#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 --------------- [](#ī¸-installation) You can install the package via composer: ``` composer require mapo-89/laravel-avatar-manager ``` ⚙ī¸ Configuration ---------------- [](#ī¸-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 [](#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 [](#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 [](#execute-tests) The tests can be executed with various commands: ``` composer test ./vendor/bin/phpunit --testdox --stderr ./vendor/bin/pest ``` ### Changelog [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. ### Security [](#security) If you discover any security related issues, please email instead of using the issue tracker. Credits ------- [](#credits) - [Manuel Postler](https://github.com/mapo-89) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. Laravel Package Boilerplate --------------------------- [](#laravel-package-boilerplate) This package was generated using the [Laravel Package Boilerplate](https://laravelpackageboilerplate.com). ### Health Score 32 — LowBetter than 72% of packages Maintenance55 Moderate activity, may be stable Popularity6 Limited adoption so far Community6 Small or concentrated contributor base Maturity53 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~8 days Total 5 Last Release 299d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/72ebd5bd16b28366468c5f9cdafe5350f343eaa054995d00f4b4640c5c27767b?d=identicon)[mapo-89](/maintainers/mapo-89) --- Top Contributors [![mapo-89](https://avatars.githubusercontent.com/u/118180259?v=4)](https://github.com/mapo-89 "mapo-89 (31 commits)") --- Tags phplaravelgravataravatar ### Code Quality TestsPest ### Embed Badge ![Health badge](/badges/mapo-89-laravel-avatar-manager/health.svg) ``` [![Health](https://phpackages.com/badges/mapo-89-laravel-avatar-manager/health.svg)](https://phpackages.com/packages/mapo-89-laravel-avatar-manager) ``` ### Alternatives [laravolt/avatar Turn name, email, and any other string into initial-based avatar or gravatar. 2.0k5.4M31](/packages/laravolt-avatar)[monicahq/laravel-cloudflare Add Cloudflare ip addresses to trusted proxies for Laravel. 3372.7M4](/packages/monicahq-laravel-cloudflare)[kra8/laravel-snowflake Snowflake for Laravel and Lumen. 188402.3k6](/packages/kra8-laravel-snowflake)[bezhansalleh/filament-google-analytics Google Analytics integration for FilamentPHP 205144.8k5](/packages/bezhansalleh-filament-google-analytics)[laragear/preload Effortlessly make a Preload script for your Laravel application. 119363.5k](/packages/laragear-preload)[napp/xray-laravel AWS X-Ray for Laravel applications. 61407.3k](/packages/napp-xray-laravel) PHPackages Š 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)