Deterministic avatar faces from any string. A PHP/Laravel port of the facehash JavaScript library.
Generates unique, consistent SVG avatars based on a name, email, or any string input. No GD, Imagick, or external services required — pure SVG output.
- PHP 8.2+
- Laravel 11, 12 or 13
composer require saade/facehashuse Saade\Facehash\Facades\Facehash;
// Generate an SVG string
$svg = Facehash::name('Saade')->toSvg();
// Embed as a data URI in an <img> tag
$uri = Facehash::name('Saade')->toUri();
// <img src="{{ $uri }}" alt="Avatar">All methods return a new instance (immutable), so you can chain freely without affecting the original.
Required. The input string to generate the avatar from. The same string always produces the same face.
Facehash::name('alice@example.com')->toSvg();Avatar dimensions in pixels. Default: 40.
Facehash::name('Saade')->size(128)->toSvg();Background style. Accepts 'gradient' or 'solid'. Default: 'gradient'.
Facehash::name('Saade')->variant('solid')->toSvg();Avatar shape. Accepts 'square', 'squircle', or 'circle'. Default: 'circle'.
Facehash::name('Saade')->format('squircle')->toSvg();Adds a CSS blink animation to the eyes inside the SVG. Default: false.
Facehash::name('Saade')->blink()->toSvg();Show the first letter of the name below the eyes. Default: true.
Facehash::name('Saade')->initial(false)->toSvg();Override the color palette. Each avatar picks a color deterministically from this array.
Facehash::name('Saade')->colors(['#6366f1', '#8b5cf6', '#a78bfa'])->toSvg();| Method | Returns |
|---|---|
toSvg() |
Raw SVG string |
toBase64() |
Base64-encoded SVG string |
toUri() |
Data URI (data:image/svg+xml;base64,...) |
The package includes an optional GET route that serves avatars as image/svg+xml responses with long-lived cache headers. The route is disabled by default — enable it in your config:
// config/facehash.php
'route' => [
'enabled' => true,
// ...
],GET /facehash?name=Saade
| Parameter | Type | Default | Description |
|---|---|---|---|
name |
string | required | Input string |
size |
int | 40 |
Size in pixels (16–1024) |
variant |
string | gradient |
gradient or solid |
format |
string | circle |
square, squircle, or circle |
initial |
bool | true |
Show initial letter |
blink |
bool | false |
Enable blink animation |
colors[] |
string[] | — | Custom hex color palette |
<!-- Basic usage -->
<img src="/facehash?name=Saade" alt="Avatar">
<!-- Larger, solid variant -->
<img src="/facehash?name=Saade&size=128&variant=solid" alt="Avatar">
<!-- Custom colors -->
<img src="/facehash?name=Saade&colors[]=%236366f1&colors[]=%238b5cf6" alt="Avatar">{{-- Inline SVG --}}
{!! Facehash::name($user->name)->size(48)->toSvg() !!}
{{-- As <img> src --}}
<img src="{{ Facehash::name($user->name)->size(48)->toUri() }}" alt="{{ $user->name }}">
{{-- Via route --}}
<img src="{{ route('facehash', ['name' => $user->name, 'size' => 48]) }}" alt="{{ $user->name }}">Publish the config file:
php artisan vendor:publish --tag=facehash-configThis creates config/facehash.php:
return [
'defaults' => [
'size' => 40,
'variant' => 'gradient', // 'gradient' or 'solid'
'format' => 'circle', // 'square', 'squircle', or 'circle'
'initial' => true,
'blink' => false,
],
'colors' => ['#ec4899', '#f59e0b', '#3b82f6', '#f97316', '#10b981'],
'route' => [
'enabled' => false,
'prefix' => 'facehash',
'middleware' => ['web'],
'cache_control' => 'public, max-age=31536000, immutable',
],
];defaults — Default values for the builder. Any method call overrides these per-instance.
colors — The color palette. Each avatar deterministically picks one color from this array. The default palette uses Tailwind CSS 500-weight colors.
route.enabled — Set to true to register the HTTP endpoint. Disabled by default.
route.prefix — URL path for the HTTP endpoint.
route.middleware — Middleware applied to the route.
route.cache_control — Cache-Control header value. The default serves immutable responses cached for 1 year — safe because the same input always produces the same output.
- The input string is hashed to a deterministic 32-bit integer
- The hash selects a face type (round, cross, line, curved), a color, and a rotation (3D look direction)
- The SVG renderer composites: clip path (circle, square, or squircle), background color, gradient overlay, eye shapes, position offset, and initial letter
- The same string always produces the exact same SVG — across requests, servers, and deployments
The hash function is a direct port of the JavaScript original, producing identical output for any given input.
| Type | Description |
|---|---|
| Round | Circular dot eyes |
| Cross | Plus-sign shaped eyes |
| Line | Horizontal bar eyes |
| Curved | Sleepy/arc eyes |
4 face types × 5 colors × 9 rotation positions = 180 visually distinct avatars from the default palette. Custom color palettes increase this further.
A standalone demo page is included for testing without Laravel:
php -S localhost:8080 public/index.phpOpen http://localhost:8080 for the avatar gallery, variant comparisons and an interactive playground, or /cover for the social card.
The documentation at facehash.saade.dev is a static site generated from this repo and published to GitHub Pages by .github/workflows/pages.yml on every push to main. The domain lives in $siteUrl at the top of docs/build.php, which drives both the canonical/OG URLs and the CNAME file in the artifact.
php docs/build.php # build into _site/
php -S localhost:8080 -t _site # preview
node docs/parity.mjs # check the browser port against the PHP rendererEvery avatar on the page is rendered at build time by the PHP renderer. The playground needs to render arbitrary names in the browser, so docs/assets/facehash.js ports the hash and SVG composition to JavaScript — it takes the face paths, sphere positions, palette and defaults from docs/build.php's export of the PHP classes, and docs/parity.mjs diffs both implementations across a matrix of inputs so they cannot drift apart.
This package is a PHP/Laravel port of facehash by Cossistant. The original JavaScript library provides the face SVG data, hash algorithm, and rendering logic that this package faithfully reproduces.
MIT