Filament Facehash Laravel Package

Product Decisions This Supports

• Kill the "empty avatar" backlog item. Every product with a Filament admin has a low-grade, never-prioritized defect: users who never uploaded a photo render as identical grey circles. This package resolves it as a fallback provider, so it competes with—and beats—the alternative roadmap item "build avatar upload + storage + image resizing." That's a build-vs-buy decision resolvable in an afternoon with a one-line revert.
• De-risk the "identity in admin" initiative without touching the data layer. There are no migrations, no storage bucket, no queue worker, and no GD/Imagick requirement (a real constraint if your container images or shared hosting are minimal). Adoption is additive and reversible per panel, which means it can ship to a low-traffic internal panel before it ever touches a customer-facing surface.
• Cheap differentiation on support and moderation surfaces. Deterministic faces give operators a stable visual handle on users: "the pink one" becomes shared team vocabulary in tickets, screenshots, and Slack threads. That's a modest but real reduction in mis-identification, and it's the kind of thing customers notice as polish without ever filing a request for it.
• A themable, per-panel design token. size(), variant(), initial(), and colors() are product knobs, not just code: Solid for dense tables where an initial must stay legible, Gradient for the client-facing portal, palettes aligned to brand tokens. Different panels legitimately deserve different treatments, and this supports that without a design-system project.
• Consistency beyond the panel. The HasFacehashAvatar trait means the same face appears in Blade views, Inertia props, and in-app notifications—so the identity convention doesn't stop at the admin boundary.
• Not a decision this supports: transactional email. SVG data-URI rendering is unreliable across mail clients. Keep that requirement out of the pilot scope explicitly, or you'll burn credibility on a predictable failure.

Where the PM has to own the tradeoff: determinism is both the feature and the footgun. Two "John Smith" accounts get identical faces; a rename silently produces a brand-new face. On a moderation or user-management screen where disambiguation is the job, this can actively mislead. Mitigate with a unique name-derivation policy (email or a per-ID fallback), pilot where collisions are rare, and document the one-line escape hatch before launch—not after.

When to Consider This Package

Adopt when:

• You run a Filament panel and a meaningful share of users have no uploaded avatar. The "before" is visibly bad and the fix is a fallback, so no existing imagery is displaced.
• Your runtime is constrained—no GD/Imagick, no object storage, no appetite for an upload pipeline or its retention/PII obligations.
• You want a themable avatar treatment per panel and would otherwise hand-roll a Filament AvatarProvider (which is essentially all this adapter is).
• You need it outside panels too, via the model trait.
• You can absorb the risk profile: single maintainer, ~4 stars, zero dependents, a thin adapter over a separate generator package. Keep your own determinism test so a composer update can't silently reshuffle everyone's face.

Look elsewhere—or build the twenty lines yourself—when:

• Avatars are a customer-facing identity feature rather than an internal affordance. Real photo upload with moderation, CDN delivery, and cache headers is a different product; deterministic SVG won't satisfy it.
• Disambiguation is the primary job (trust & safety, KYC review, billing). Collisions and rename-churn are user-visible confusion, and the math works against you.
• Avatars must render in email.
• Your CSP posture is rigid and img-src data: isn't negotiable. Check this before committing; it fails in production and passes in dev, which is the worst possible failure mode.
• Heavy list views are already payload-sensitive. Generation is per-avatar per-render and inlined as base64 into the Livewire document. Measure your largest table before and after; if the delta hurts, scope it down rather than discovering it from a user complaint.
• You need vendor confidence signals for a procurement or architecture review. Size the risk honestly instead of citing stars upstream.

How to Pitch It (Stakeholders)

For executives (30 seconds): A small, reversible fix for a visible quality gap. Today, users without a photo show as identical grey circles across our admin—which makes support screenshots and moderation harder to read. This gives each name a stable, on-brand generated face. No new infrastructure, no storage, no data migration, no ongoing ops. One line per panel, and it's a fallback—uploaded photos still win, so nothing existing changes. Reverting is deleting that line.

For engineering (the parts that matter): It's a presentation-layer fallback, not a data-layer commitment. It contributes an AvatarProvider implementation wired via ->defaultAvatarProvider(...), a plugin object carrying the fluent styling API, and a trait exposing facehash_avatar_url for Blade and notifications. Output is a pure-SVG data: URI generated in PHP at render time—no extensions, no config file to publish, no migrations. Rollout is one low-traffic panel first; exit cost is roughly one class if the package stalls, which defuses the single-maintainer concern. Two asks before merge: one determinism test plus one assertSee('data:image/svg+xml') integration assertion, and an explicit constraint pinning the underlying generator package—pinning the adapter alone does not pin the generator. Confirm img-src data: in the production CSP, and don't pass the data URI into queued notification constructors.

The honest caveats to state up front, not later: low adoption signals (few stars, no dependents), one maintainer, and determinism that cuts both ways—duplicate names collide and renames change the face. We're accepting that because the blast radius is a fallback avatar with a one-line rollback, and because the alternative is either living with grey circles or funding an upload pipeline nobody asked for.