Laravel Instantavatar Laravel Package

Getting Started

This is a thin Laravel wrapper (service provider + facade + publishable config) around a PHP avatar-generation engine, dating from the Laravel 5.0/5.1 era. Treat it as an integration layer, not a framework: almost all behaviour lives in the underlying generator library, so read both.

Minimal steps:

1. composer require vinicius73/laravel-instantavatar. Expect the composer.json to pin laravel/framework to a ~5.0-style constraint. On Laravel 5.5+ this may block installation; either install with --ignore-platform-reqs after verifying nothing genuinely breaks, or fork and widen the constraint. Do not fight this in production without testing the service provider boot on your target version.
2. Register manually unless auto-discovery is declared in extra.laravel:
   • config/app.php → providers[] = Vinicius73\InstantAvatar\InstantAvatarServiceProvider::class
   • config/app.php → aliases['InstantAvatar'] = Vinicius73\InstantAvatar\Facades\InstantAvatar::class (verify namespace in the README/facade file).
3. Publish config: php artisan vendor:publish --provider="Vinicius73\InstantAvatar\InstantAvatarServiceProvider" (older installs use --tag=config).
4. Confirm php -m | grep -i gd — image output almost certainly requires GD (freetype too if text is rendered).

Where to look first: the README for the canonical call signature, then src/ for the facade class — its getFacadeAccessor() gives you the container binding, which is the single most useful fact for overriding or testing. Then config/instantavatar.php for size/colour/format defaults.

First use case: a stable default avatar for users. Seed the generator with something immutable ($user->id or a hash of the email) so the same user always gets the same avatar, then either render on demand from a route or write the file once at registration.

Implementation Patterns

Seeded, deterministic avatars. The whole value proposition collapses if the avatar changes on every page load. Always pass a seed derived from stable user data, and verify determinism explicitly before shipping (see Gotchas — the underlying engine may not seed its RNG for you). A quick assert that two consecutive generations with the same seed produce identical bytes saves a lot of pain later.

Generate once at registration, serve from disk. In a Registered event listener (or a model observer on created), generate the file into storage/app/avatars/{id}.png. This keeps request latency flat and removes runtime dependency on GD config on every node. Backfill existing users with a small artisan command that iterates in chunks.

Or serve on demand via a route. Useful when you don't want file storage: a route with response($png)->header('Content-Type', 'image/png'), a long Cache-Control/ETag keyed on the seed hash, and a Last-Modified from updated_at. Guard the size/colour query params with a whitelist — never let a user pass arbitrary dimensions into an image library.

Blade / model integration. Add a getAvatarAttribute() accessor on User that falls back to a generated avatar when no uploaded one exists, and use <img src="{{ $user->avatar_url }}">. Keeping the fallback inside the accessor means you can swap in a real upload later without touching views.

Testing. Mock the facade (InstantAvatar::shouldReceive('...')) for feature tests that only care about the URL/attribute, and use Storage::fake('avatars') to assert the file was written. For the generation itself, one integration test asserting a non-empty PNG and the image/png magic bytes is enough.

Gotchas and Tips

• Abandoned since 2015. No Laravel 5.5+ auto-discovery, no PHP 8 compatibility work, no security patches. Budget for a fork if you adopt it, or use the underlying library directly and skip the wrapper — the wrapper buys you very little beyond a config file.
• Determinism is not guaranteed. Many identicon-style generators call mt_rand()/rand() without seeding. If the same input yields different avatars, either mt_srand(crc32($seed)) before the call or (better) generate once and cache the file. This is the most common "why is my avatar different every refresh" bug.
• Config caching. After editing config/instantavatar.php, run php artisan config:cache/config:clear. A stale cached config is the usual cause of "my colour change did nothing".
• Class not found / provider not booting. composer dump-autoload and php artisan clear-compiled. On newer Laravel versions the provider may boot but silently fail if it touches removed helpers or a deprecated container API — check storage/logs/laravel.log rather than the browser.
• GD vs Imagick. If output is a blank or black image, you have GD without freetype (text) or the wrong driver selected in config. Verify with gd_info() and check the driver key in the published config.
• Never echo raw image bytes from a controller that also renders a view. Return a proper binary response or the PNG header will be polluted by buffered output.
• Filesystem permissions. Generated avatars written under storage/ fail silently on misconfigured queue workers (www-data vs forge). Log a warning if file_put_contents returns false.
• Extension points. Because everything resolves through the facade accessor, you can $this->app->bind() your own implementation for swapping engines or adding S3 storage. Likewise, InstantAvatar::extend(...) (if exposed) is the cleanest place to inject a differently-seeded generator.
• Migrating off it later is easy if you store the generated files rather than generating on the fly — another argument for the write-once pattern.