Avatar Bundle Laravel Package

Getting Started

Start with composer require mrgoodbytes8667/avatar-bundle and check the installed version line in your composer.json — the recent release is 0.10.2, and the diff shown jumps from 0.10.0, so treat anything in the 0.10.x line as pre-1.0 and pin it explicitly rather than floating ^0.10.

Where to look first:

1. The bundle's service definitions — this is a Symfony-style bundle (avatar-bundle), not a Laravel service provider. If you're wiring it into a Laravel app you'll be instantiating/resolving the avatar generator class directly from the container or a thin adapter service, so locate the generator service ID in the bundle's Resources/config (or config/) directory before you touch any controllers.
2. The configuration file — copy/merge the bundle's config into your application config and confirm the key namespace the bundle expects. Getting the root key wrong is the most common cause of "why is my avatar blank" on first run.
3. The deprecation notice for UserParamConverter — if any of your code (or a tutorial you're following) converts a route parameter directly into a user object for avatar rendering, that path is now deprecated. Grep for UserParamConverter / param_converter before you build on it.

First use case: render a deterministic avatar for a user record. Resolve the generator service, pass the user's identity fields (initials/name/email hash — whichever the generator exposes), and emit the resulting URL or image response from a single controller action. Get that end-to-end working before layering caching or templating helpers on top.

Implementation Patterns

Single controller action, streamed response. Keep avatar rendering in one thin endpoint (e.g. /avatar/{seed}) that resolves the generator, produces the image, and returns it with explicit Content-Type and cache headers. This keeps the generator out of Blade/Twig templates and gives you one place to swap backends later.

Resolve the generator via DI, not new. Autowire the generator service into your controller/helper. Because this is a bundle rather than a Laravel package, don't assume app() will resolve it by a short class alias — bind the concrete class in a service provider register() if you're adapting it into Laravel.

Precompute URLs, not images. Store or derive the avatar URL in your view model / API resource and let the browser and your HTTP cache do the work. Regenerating images on every page render is the classic performance trap with avatar packages.

Migrating off UserParamConverter (v0.10.2 deprecation). The conversion step is being phased out. Move to explicit handling:

// Before (deprecated pattern): route param auto-converted to a user object
// After: accept the scalar, resolve it yourself
public function show(string $seed, AvatarGenerator $generator): Response
{
    $user = User::findOrFail($seed);

    return $generator->render($user->avatarSeed());
}

For Symfony consumers, the same idea applies via an Argument ValueResolver or a plain controller argument. Doing this now means the removal at 1.0 is a no-op for you.

Layer your own cache key. Wrap the generator call in Cache::remember() (or Symfony Cache) keyed on seed + avatar config hash + version, and include the package version in the key. When you bump avatar-bundle, the key changes and you don't serve stale images in a new style.

Determinism is a feature — lean on it. Identicon/initials generation should be pure: same input, same output. That means you can generate on demand, never persist the binary, and safely put a long Cache-Control on the response.

Gotchas and Tips

• Pre-1.0 churn is real. Going from 0.10.0 to 0.10.2 already carries a deprecation. Assume the UserParamConverter will be removed (not just deprecated) at 1.0 and budget the migration before you pin upward. Lock to 0.10.2 exactly in composer.lock and read the changelog on every bump.
• The changelog is sparse. The release note covers only the deprecation, and v0.10.1 isn't described at all in the provided range. Before upgrading in a real project, diff v0.10.0...v0.10.2 on GitHub yourself rather than trusting the summary — small patch numbers on pre-1.0 packages routinely hide signature changes.
• Deprecations are silent by default. The UserParamConverter notice will surface in the Symfony profiler's deprecation log or your deprecation channel, not as an exception. Turn on deprecation logging in dev (framework.php_errors.log / APP_DEBUG) or you'll discover it only when the class disappears.
• Extension requirements. Image generation typically needs GD or Imagick compiled in. If avatars return empty or 500 on one environment but not another, check php -m before you debug the bundle config.
• Config merge order. Bundle defaults are merged shallowly in most Symfony setups. If your avatar config block partially overrides defaults, verify the resulting merged config in the container dump rather than eyeballing the YAML — partial overrides are where "it ignored my setting" comes from.
• Don't fight the determinism. If you find yourself adding a rand() seed or a timestamp to the avatar input to "fix" caching, you've inverted the design. Clear the cache key instead.
• Extension points to prefer. Keep your usage behind a small interface of your own (AvatarService::urlFor($user)), even if it's a one-method wrapper. Given the pre-1.0 status and the active deprecation, that wrapper is what will make the eventual 1.0 upgrade a single-file change instead of a project-wide grep.