Weave Code
Avatar Laravel Package
laravolt/avatar
Generate unique, colorful initials-based avatars for any user in Laravel or plain PHP. Output as base64 data-URI directly in views, save to PNG/JPG with custom quality, or use Gravatar. Customizable config, auto-discovery, works with Laravel 10-13 and PHP 8.3+.
Turn name, email, and any other string into initial-based avatar or gravatar.
Frequently asked questions about Avatar
- How do I install laravolt/avatar in a Laravel app?
- Run composer require laravolt/avatar. The service provider and Avatar facade are registered automatically through Laravel package auto-discovery, so no manual registration is needed. Publishing the config with php artisan vendor:publish --provider="Laravolt\Avatar\ServiceProvider" is optional and only creates config/laravolt/avatar.php. There are no migrations, routes, or other publish steps, so a working prototype takes minutes.
- Which PHP, Laravel, and Intervention Image versions does laravolt/avatar support?
- Version 7.x requires PHP 8.3 or newer with Laravel 10 through 13 and Intervention Image ^4.0. Version 6.x requires PHP 8.1 or newer with Laravel 10 through 12 and Intervention Image ^3.0. Version 5.x requires PHP 8.0 or newer with Laravel 9 through 11 and Intervention Image ^2.0. The practical gate is Intervention Image: apps still on v2 must use the 5.x line, while v3 is a hard requirement for 6.x.
- How do I render laravolt/avatar as a base64 data URI in a Blade view?
- Call Avatar::create('Joko Widodo')->toBase64(), which returns a string like data:image/png;base64,iVBORw0KGg... and can be dropped straight into an img src attribute. It is the simplest placement because it needs zero storage or routing infrastructure. The trade-off is that the PNG is encoded on every page render, so cache the result or pre-render for high-traffic pages.
- Can I save laravolt/avatar output as a PNG or JPG file?
- Yes. Use save('sample.png') for PNG, or save('sample.jpg', 100) to write a JPEG at the given quality. Pre-rendering at user creation or in a queued job gives the best runtime profile because the encode cost is paid once. The catch is that you own the storage lifecycle, including regenerating the file when a user changes their name. If you need watermarks, resizing, or WebP, getImageObject() returns an Intervention Image instance you can post-process.
- Does laravolt/avatar work outside Laravel in plain PHP?
- Yes. The package was originally built for Laravel but can be instantiated directly with new Avatar($config) using a plain array instead of the published config file. That dual entry point means the same rendering policy can be reused in queue workers, CLI backfills, and console commands without any HTTP coupling. You still need the GD or Imagick extension and a compatible Intervention Image version installed.
- How do I use Gravatar with laravolt/avatar and is the hashing still MD5?
- Call Avatar::create('[email protected]')->toGravatar() to get a Gravatar URL for the email address. Hashing changed to SHA-256 in version 6.1.0, which produces a 64-character hex digest and therefore different URLs than the legacy MD5 behavior. If you store Gravatar URLs or build dedupe keys from the hash, audit them before and after upgrading, and verify against the current Gravatar API.
- How do I customize avatar colors, fonts, shapes, and themes?
- Publish the config and edit config/laravolt/avatar.php, which controls fonts, background and foreground palettes, shape, and the ascii and rtl flags. Background, foreground, and font are seeded from the supplied name, so colors are stable per user by default. Calling setTheme(['a','b']) introduces randomized selection, so confirm the seeding is stable across versions before treating color as a user-facing identity cue.
- Do I need the GD or Imagick PHP extension for laravolt/avatar?
- Yes. GD or Imagick must be compiled into every runtime that renders avatars: web, queue workers, and CLI. A missing extension fails as a runtime exception on the first avatar render rather than at deploy time, which is a classic works-in-CI-fails-in-production pattern. Assert the extension in your health check or a boot-time check to catch it early.
- Is laravolt/avatar SVG output safe to inline in Blade, or is there an XSS risk?
- toSvg() emits a text element containing initials derived from user-supplied names, so the markup contains untrusted input. The package does not control how you embed it: if you inject the SVG inline into HTML instead of serving it as image/svg+xml, XML escaping becomes your responsibility. Prefer the toBase64() data URI or serve the SVG with the correct content type, and sanitize names, especially with the ascii and rtl options widening the input space.
- How do I upgrade laravolt/avatar from 5.x to 6.x or 7.x?
- Moving from 5.x to 6.x switches Intervention Image from v2 to v3 and requires PHP 8.1 or newer, while 6.x to 7.x moves to Intervention Image v4 and requires PHP 8.3 with Laravel 10 through 13. Gravatar hashing changed to SHA-256 in 6.1.0, so re-check any cached URLs or digests. Apps stuck on Intervention v2 should stay on the 5.x line, which caps Laravel support at 11. Before relying on the package, also review the bundled fonts: Open Sans is OFL, but Rockwell is a Monotype trademark and may need swapping for commercial deployments.
Weaver
How can I help you explore Laravel packages today?