Gravatar Laravel Package

Product Decisions This Supports

• Avatar strategy (build vs. buy vs. skip): This package is a thin, typed URL builder for Gravatar images and profiles. It answers the "how" of avatars, not the "whether." The real product decision it supports is whether Gravatar is our default identity surface at all — and it keeps that decision cheap and reversible, since the dependency can be ripped out without data migration.
• Security posture on third-party data: 7.0.0 removes Profile::getData() entirely, eliminating a file_get_contents() + unserialize() path on remote data (CWE-502). This closes a deserialization risk that would otherwise have to be explained in a security review. It converts "library may fetch and deserialize untrusted remote payloads" into "library only builds strings" — a meaningfully smaller attack surface and a much easier compliance conversation.
• Privacy / DPA review: Hashing moves from MD5 to SHA-256. MD5 of an email address is trivially reversible against a known address list; SHA-256 is not. Sending a hash of a user's email to a third party is still a pseudonymous identifier disclosure, but the upgrade removes the "effectively plaintext" argument. This is the kind of change that unblocks a privacy sign-off rather than creating work.
• Owning the fetch layer: Because the library no longer performs HTTP, profile enrichment becomes an explicit product decision with an explicit owner. If we want "show the user's Gravatar bio/location," we now build it — with caching, timeouts, retries, and a fallback. If we don't want it, we simply don't build it and the dependency stays a pure URL builder. That is a better decision boundary than the old implicit one.
• Roadmap sequencing / platform dependency: 7.0.0 uses PHP 8.4 features (typed class constants, property hooks, asymmetric visibility), which means a hard PHP 8.4 floor. This release is therefore gated on our runtime upgrade and should be scheduled behind it, not in parallel. It becomes a data point for the "when do we move to 8.4" conversation rather than a reason to move.
• Migration scoping for the current release: The breaking changes map directly to backlog items — MD5→SHA-256 invalidates any persisted avatar URLs, CDN cache keys, or hash columns; the //www.gravatar.com → https://gravatar.com host change breaks protocol-relative URL assertions; removal of ProfileFormat/ProfileHasFormat/InvalidProfileFormatException breaks any non-JSON profile usage; read-only properties break direct assignment (->email = , ->initialsName = , ->forceDefault = ); Gravatar::profile()/profiles() no longer take $format.
• Testability and error handling as product quality: New GravatarInterface (extends Stringable) lets us type-hint and fake avatars in tests and swap implementations later. New GravatarExceptionInterface gives a single catch point, so a Gravatar problem degrades gracefully to a fallback avatar instead of a 500. Both reduce the blast radius of a third-party dependency on user-facing pages.

When to Consider This Package

Adopt when:

• The application is on PHP 8.4 already, or that upgrade is committed and dated. On PHP 8.2/8.3, 7.0.0 is simply not installable — pin 6.x or defer.
• You want avatars with zero infrastructure and zero vendor contract — no upload storage, no image resizing pipeline, no CDN origin.
• You want a maintained, typed, PHPStan-max, Pest-covered wrapper instead of hand-rolled md5()/sha256() + string concatenation scattered across Blade templates and controllers. The 7.0.0 changelog is the argument for the package's existence: Gravatar changed its API version, hashing, and canonical host, and the library absorbed all three.
• You want the library to track Gravatar's API surface so we don't discover a deprecation from a broken page.
• Low lock-in matters: the public surface is essentially url(), copy(), and a handful of fluent setters.

Look elsewhere or defer when:

• Runtime is below PHP 8.4. This is a hard blocker, not a nice-to-have.
• You need the library to fetch profile data. It no longer does. You will own the HTTP client, caching, retry/timeout policy, rate limiting, and error handling — estimate that work before assuming this release is "free."
• You depend on non-JSON profile formats or the removed ProfileFormat enum / ProfileHasFormat trait. There is no replacement; v3 is JSON-only.
• You need guaranteed avatar availability. Gravatar is opt-in; a large share of users have no Gravatar. This package must be paired with a fallback (initials, local upload, generated identicon) or it is not a complete avatar strategy.
• Privacy policy forbids sending email-derived identifiers to any third party. Then the answer is no Gravatar at all, regardless of hash strength.
• You want image transformation (crop, resize beyond Gravatar's query params, format negotiation). Removed format selection plus Gravatar's limited params means a real image pipeline is a different product.

Adoption checklist for the 7.0.0 bump:

1. Confirm PHP 8.4 in all environments, including CI and any queue workers.
2. Grep for direct property assignment: ->email =, ->initials =, ->initialsName =, ->forceDefault = — convert to methods.
3. Grep for getData(, ProfileFormat, ProfileHasFormat, InvalidProfileFormatException, and any $format argument on profile()/profiles().
4. Audit persisted data and caches for MD5 email hashes and //www.gravatar.com host strings; plan invalidation, not just a code change.
5. Decide explicitly whether profile enrichment is in scope. If not, adopt strictly as a URL builder and document that.
6. Confirm fallback behavior: wrap url() calls and catch GravatarExceptionInterface where avatars render.

How to Pitch It (Stakeholders)

To executives: This is a small, free, open-source dependency that gives users profile avatars without us storing or serving images. The new 7.0.0 release is a maintenance upgrade, not a feature bet: it removes a genuine security weakness (the old version fetched remote data and deserialized it, a known vulnerability class), strengthens the privacy of the email-derived identifiers we send, and catches us up to Gravatar's current API before the old one is retired. The cost is a scoped, mechanical migration whose only real gate is our PHP 8.4 upgrade — which we need on the roadmap anyway. No new spend, less custom code to maintain, and the fallback path keeps avatars rendering if Gravatar is unavailable.

To engineering: Treat 7.0.0 as a semver-major with a hard PHP 8.4 floor. Migration is mostly mechanical — property assignment becomes method calls, $format arguments and the format enum/trait disappear, getData() is gone — but two items need real thought: (1) any MD5-derived hashes or absolute Gravatar URLs we've persisted in the database, cache keys, CDN config, or snapshot tests must be invalidated, not just recompiled; (2) we now own profile fetching, so if we keep that feature it needs Laravel Http, a cache TTL, timeouts, and a graceful fallback. Upside: PHPStan at max with zero errors, a Pest suite covering every class, composer lint/analyse/test/check scripts, GravatarInterface for type-hinting and fakes, and GravatarExceptionInterface for a single catch point around avatar rendering. Recommended stance: adopt as a URL builder only, wrap every call site in a try/catch with an initials fallback, and decline the profile-enrichment feature unless a product requirement justifies building it.