PHPackages saade/facehash - 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. saade/facehash ActiveLibrary[Utility & Helpers](/categories/utility) saade/facehash ============== Deterministic avatar faces from any string. Lightweight, pure SVG output. Laravel integration. v1.2.0(2mo ago)41.6k↓15.4%1MITPHPPHP ^8.2 Since Feb 17Pushed 2mo agoCompare [ Source](https://github.com/saade/facehash)[ Packagist](https://packagist.org/packages/saade/facehash)[ GitHub Sponsors](https://github.com/saade)[ RSS](/packages/saade-facehash/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (3)Dependencies (2)Versions (4)Used By (1) Facehash for Laravel ==================== [](#facehash-for-laravel) [![Facehash](art/cover.png)](art/cover.png) Deterministic avatar faces from any string. A PHP/Laravel port of the [facehash](https://facehash.dev) 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. Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 11 or 12 Installation ------------ [](#installation) ``` composer require saade/facehash ``` Quick Start ----------- [](#quick-start) ``` use Saade\Facehash\Facades\Facehash; // Generate an SVG string $svg = Facehash::name('Saade')->toSvg(); // Embed as a data URI in an tag $uri = Facehash::name('Saade')->toUri(); // ``` API --- [](#api) All methods return a new instance (immutable), so you can chain freely without affecting the original. ### `name(string $name)` [](#namestring-name) **Required.** The input string to generate the avatar from. The same string always produces the same face. ``` Facehash::name('alice@example.com')->toSvg(); ``` ### `size(int $pixels)` [](#sizeint-pixels) Avatar dimensions in pixels. Default: `40`. ``` Facehash::name('Saade')->size(128)->toSvg(); ``` ### `variant(string $variant)` [](#variantstring-variant) Background style. Accepts `'gradient'` or `'solid'`. Default: `'gradient'`. ``` Facehash::name('Saade')->variant('solid')->toSvg(); ``` ### `format(string $format)` [](#formatstring-format) Avatar shape. Accepts `'square'`, `'squircle'`, or `'circle'`. Default: `'circle'`. ``` Facehash::name('Saade')->format('squircle')->toSvg(); ``` ### `blink(bool $enable = true)` [](#blinkbool-enable--true) Adds a CSS blink animation to the eyes inside the SVG. Default: `false`. ``` Facehash::name('Saade')->blink()->toSvg(); ``` ### `initial(bool $show = true)` [](#initialbool-show--true) Show the first letter of the name below the eyes. Default: `true`. ``` Facehash::name('Saade')->initial(false)->toSvg(); ``` ### `colors(array $colors)` [](#colorsarray-colors) Override the color palette. Each avatar picks a color deterministically from this array. ``` Facehash::name('Saade')->colors(['#6366f1', '#8b5cf6', '#a78bfa'])->toSvg(); ``` ### Output Methods [](#output-methods) MethodReturns`toSvg()`Raw SVG string`toBase64()`Base64-encoded SVG string`toUri()`Data URI (`data:image/svg+xml;base64,...`)HTTP Route ---------- [](#http-route) 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 ``` ### Query Parameters [](#query-parameters) ParameterTypeDefaultDescription`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### Examples [](#examples) ``` ``` Blade Usage ----------- [](#blade-usage) ``` {{-- Inline SVG --}} {!! Facehash::name($user->name)->size(48)->toSvg() !!} {{-- As src --}} {{-- Via route --}} ``` Configuration ------------- [](#configuration) Publish the config file: ``` php artisan vendor:publish --tag=facehash-config ``` This 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', ], ]; ``` ### Config Options [](#config-options) **`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. How It Works ------------ [](#how-it-works) 1. The input string is hashed to a deterministic 32-bit integer 2. The hash selects a **face type** (round, cross, line, curved), a **color**, and a **rotation** (3D look direction) 3. The SVG renderer composites: clip path (circle, square, or squircle), background color, gradient overlay, eye shapes, position offset, and initial letter 4. 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. ### Face Types [](#face-types) TypeDescriptionRoundCircular dot eyesCrossPlus-sign shaped eyesLineHorizontal bar eyesCurvedSleepy/arc eyes### Unique Combinations [](#unique-combinations) 4 face types × 5 colors × 9 rotation positions = **180** visually distinct avatars from the default palette. Custom color palettes increase this further. Demo ---- [](#demo) A standalone demo page is included for testing without Laravel: ``` php -S localhost:8080 demo.php ``` Open `http://localhost:8080` to see the avatar gallery, variant comparisons, and an interactive playground. Credits ------- [](#credits) This package is a PHP/Laravel port of [facehash](https://facehash.dev) by [Cossistant](https://github.com/cossistantcom/cossistant). The original JavaScript library provides the face SVG data, hash algorithm, and rendering logic that this package faithfully reproduces. License ------- [](#license) MIT ### Health Score 45 — FairBetter than 93% of packages Maintenance87 Actively maintained with recent releases Popularity26 Limited adoption so far Community8 Small or concentrated contributor base Maturity48 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 ~14 days Total 3 Last Release 62d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/a71deedec445b71a667043e26cdf835628920543cc54e4fba0d1cc592958e5a0?d=identicon)[saade](/maintainers/saade) --- Top Contributors [![saade](https://avatars.githubusercontent.com/u/14329460?v=4)](https://github.com/saade "saade (7 commits)") --- Tags laravelsvgavataridenticondeterministicfacehash ### Embed Badge ![Health badge](/badges/saade-facehash/health.svg) ``` [![Health](https://phpackages.com/badges/saade-facehash/health.svg)](https://phpackages.com/packages/saade-facehash) ``` ### Alternatives [barryvdh/laravel-ide-helper Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion. 14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[laravolt/avatar Turn name, email, and any other string into initial-based avatar or gravatar. 2.0k5.4M31](/packages/laravolt-avatar)[tomloprod/radiance A deterministic mesh gradient avatar generator for PHP. 1393.7k](/packages/tomloprod-radiance)[arcanedev/gravatar A library providing easy gravatar integration/generation (Laravel supported). 1986.8k](/packages/arcanedev-gravatar)[interaction-design-foundation/laravel-geoip Support for multiple Geographical Location services. 17221.0k3](/packages/interaction-design-foundation-laravel-geoip)[astrotomic/laravel-unavatar Laravel integration of unavatar service. 297.9k](/packages/astrotomic-laravel-unavatar) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)