Boredom Laravel Package

Getting Started

Confirm what the package actually does before you install it. The repo carries two contradictory descriptions: a FilamentPHP avatar provider (Boring Avatars) and a wrapper around the Bored API for random activity suggestions. Everything points to the avatar reading being correct — the vendor is a Filament plugin shop, the package name, and the 3.0.0 changelog whose only substantive line is "support filament 5". Check composer.json's require block in vendor/lara-zeus/boredom before you plan any work around it.

Install and wire it up.

1. composer require lara-zeus/boredom and immediately read the resulting constraints for filament/filament, laravel/framework, and php. Match them against your panel stack — a 3.0.0 release that exists only to track Filament 5 may not install cleanly on your Filament 3 / Laravel 11 setup.

2. Publish config if the install docs call for it (php artisan vendor:publish --tag=boredom-config is the typical Lara Zeus shape).

3. Point your panel at the provider in PanelProvider::boot() — not register():

   use Filament\Facades\Filament;
   
   public function boot(): void
   {
       Filament::setAvatarProvider(\LaraZeus\Boredom\BoredomProvider::class);
   }
   

   Verify the actual class name in src/ after install; Lara Zeus packages occasionally namespace inconsistently and the README is one of the sources that disagree about the package's purpose.

Where to look first. Open src/ in vendor/lara-zeus/boredom. A package this thin (one provider class, one config, maybe one Blade view) is faster to read than the docs. Confirm three things: (a) the provider implements Filament's avatar provider contract, (b) generation is local SVG rather than an outbound HTTP call to a Boring Avatars host — this determines whether the "no vendor egress" argument holds, and (c) whether a config file exists at all.

First real use case. An internal admin panel with a UserResource and an activity log or comment thread where half the avatars are grey circles or broken images. One config line, one smoke test — that's the whole value proposition. Budget half a day. If it takes longer than that, writing the ~50-line provider yourself has already won on cost.

Implementation Patterns

Set it per-panel, not per-app. Filament's avatar provider is scoped to the panel. Apply it to admin and back-office panels only, and leave customer-facing panels on their existing provider until you've decided whether the avatar language needs to be consistent across surfaces:

// AdminPanelProvider::boot()
Filament::setAvatarProvider(BoredomProvider::class);

Mixing providers across panels is technically fine and usually the right organisational call — internal tools don't need to match the customer portal's avatar treatment.

Keep the seam thin. Never reference LaraZeus\Boredom\* from Blade views, resources, or your User model. The only touchpoint should be the provider registration. Wrap it in an app-level class if you want an even cleaner cut:

// app/Filament/Avatars/AppAvatarProvider.php
class AppAvatarProvider implements AvatarProvider
{
    public function get(Model | Authenticatable $record): string
    {
        return app(BoredomProvider::class)->get($record);
    }
}

Swapping providers later — or reverting to an initials fallback — becomes one use statement instead of a grep across templates.

Seed deterministically and deliberately. Boring-avatars-style providers typically derive the SVG from $user->name or $user->email. Pick one consciously:

• Seed from name if the avatar should feel personal. Downside: two users named "John Smith" get identical avatars, and renaming a user silently changes their avatar.
• Seed from email for uniqueness. Downside: a user changing email loses "their" avatar, and the avatar leaks into exports where it shouldn't.

Verify which the package defaults to. This is the single most likely place for a surprise.

Pair it with a real fallback. The package solves the missing-avatar case; it does not solve the empty-name case. Configure an initials or silhouette fallback in your resource (or wrap the provider) so unnamed records still render something, and so removing the package later is a config revert rather than an incident.

Test the contract, not the SVG.

Filament::setAvatarProvider(YourProvider::class);

$this->actingAs($user)
    ->get(UserResource::getUrl('index'))
    ->assertOk()
    ->assertSee($user->name);

Don't snapshot the SVG — colours and seeds shift with every upstream tweak. Assert that the provider returns a string and the panel renders without throwing. That's the only contract you actually depend on.

Treat it as part of the Filament major bump. When you upgrade filament/filament from 3 → 4 → 5, upgrade this package in the same commit or branch, on a non-production panel first. Its major versions exist solely to track Filament majors, so bundling it into unrelated feature work is how you get an opaque view exception mid-release.

Feature-flag only if user-visible. If avatars appear anywhere a customer sees them (public profile, customer portal), gate it: config('features.bored_avatars'). Internal-only? Skip the flag — the ceremony isn't worth it.

Gotchas and Tips

The description will mislead you. The "random activity suggestions from the Bored API" blurb attached to this package describes a different product. Trust the README, composer.json, and the 3.0.0 changelog. Correct that blurb in any vendor review or procurement document too — the compliance argument (no outbound egress to an avatar CDN) only holds for the avatar reading.

One maintainer, 8 stars, 0 dependents. Nobody has walked this path publicly. Expect rough edges in config publishing, the class name, and the Blade view if one ships. You will be the first person to hit any bug on Filament 5.

Pin the exact version. "lara-zeus/boredom": "3.0.*" — not ^3.0, not *. A single-maintainer package that bumps majors to track framework majors will do so again, and you want to control when that happens. composer.lock in CI is your real pin.

Check constraints aggressively. "Only change is support Filament 5 plus a Dependabot bump" usually means the 2.x line is unmaintained rather than supported. If you're on Filament 3, verify 3.0.0 actually installs before assuming it does — the constraint may be ^5.0 only.

No HTTP means no cache, no timeout, no rate limit. That's the beauty of the avatar reading versus the (fictional) activity-API reading — nothing can go down. But it also means there's nothing to tune. If you find yourself configuring a timeout or a cache for this package, you've installed the wrong thing or you're reading the wrong docs.

Accessibility is your job, not the package's. Deterministic SVGs are decorative. Next to a name in a table, no alt is needed. Standing alone (assignee chips, comment headers without labels), they need an aria-label or adjacent visible text. Wire that in at the resource or column level; the package almost certainly doesn't ship it.

Extension points are minimal by design. Expect a config file (palette, variant), the provider class, and maybe a Blade view. If brand or accessibility requirements demand specific colours, initials treatment, or contrast ratios, you're already at the point where the ~50-line in-house version wins. Write the decision record before you start customising, so you're honest about whether you're buying or building.

Debugging a blank avatar, in order:

1. Is setAvatarProvider() in the panel's boot() and not its register()?
2. Does the record have the field the provider reads (usually name)? The provider may silently return an empty string for unnamed records.
3. Are views/assets published? Some Lara Zeus packages register their view via a published namespace; a failed publish yields a silent blank.
4. Run php artisan filament:clear-cached-components and re-render. Filament caches panel config including providers — a stale cache is the most common cause of "I set it and nothing happened."

Removal must stay one line. This is a decorative dependency in a panel you can afford to lose. The day it becomes a maintenance tax you should be able to composer remove and drop a single setAvatarProvider() call. The moment any view, migration, or model references it, you've converted a leaf dependency into foundation — which is exactly what a package with one maintainer and zero dependents must never become.