Hades Laravel Package

Getting Started

What this release means: 3.0.0 is a Filament-major-tracking release. The only functional change called out is Filament v5 support (plus a docs restructure). That makes this a compatibility major, not a feature major — the version bump exists because the underlying Filament constraint moved.

Before you install, check your Filament version. This is the whole decision:

composer show filament/filament | grep versions

• On Filament v5 → use lara-zeus/hades:^3.0
• Still on Filament v4 → stay on ^2.0; 3.0.0 will not install (or will fight your other Filament plugins in composer why-not)

Install and wire it up:

composer require lara-zeus/hades:"^3.0"

php artisan vendor:publish --tag="hades-config"
php artisan vendor:publish --tag="hades-views"   # only if you intend to override markup

Then register the plugin on the panel(s) that should use it, in your PanelProvider:

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugin(\LaraZeus\Hades\HadesPlugin::make());
}

Where to look first:

1. The package's docs/ directory at the 3.0.0 tag — 3.0.0 explicitly restructured the docs, so anything you find via search engines or old blog links is likely pointing at pre-restructure paths.
2. The plugin class (src/*Plugin.php) — its fluent methods are the real API surface, and it's small enough to read in one sitting.
3. The published config/hades.php — this is where per-panel/per-model behaviour is usually toggled.

First use case: register the plugin on a throwaway panel first, boot it, and confirm the navigation entries / pages render before touching your production panel. That single smoke test tells you whether your Filament v5 upgrade is actually complete, because Hades will surface any Blade/Tailwind or Livewire incompatibility immediately.

Implementation Patterns

Treat the upgrade as a paired migration, not a package bump. Hades 3.0.0 only makes sense alongside a Filament v4 → v5 upgrade. Do it in one branch:

git checkout -b upgrade/filament-v5
composer require filament/filament:"^5.0" -W
composer require lara-zeus/hades:"^3.0" -W
php artisan optimize:clear
php artisan filament:upgrade   # if your Filament version provides it

Then run your test suite and click through every Hades-backed screen manually — Filament majors routinely change Blade component markup and Tailwind utility output, so visual regressions won't be caught by unit tests.

Keep plugin configuration in the panel, not in config. The most maintainable pattern with Lara Zeus packages is to configure per-panel via the fluent plugin API and leave config/hades.php for defaults:

->plugin(
    HadesPlugin::make()
        ->navigationGroup('Settings')
        // ...package-specific fluent options here
)

This matters the moment you have more than one panel (e.g. AdminPanel + AppPanel), because a single global config file can't express "enabled for admins, hidden for tenants."

Override views, don't fork the package. Publish views to resources/views/vendor/hades/ and edit there. After a major like this, the safest override workflow is to publish into a temp directory and diff against what you already customised:

php artisan vendor:publish --tag="hades-views" --force
git diff resources/views/vendor/hades

Any diff you see is markup that changed under you — those are your review targets.

Use it as the reference implementation for your own Filament plugins. The v5 bump here is a good template: constrain the Filament major in composer.json, bump the package major in lockstep, and ship the docs update in the same PR (the chore: align docs structure commit in this release is exactly that discipline).

Test with Livewire's helpers, not HTTP assertions, for anything that renders a Filament page — Livewire::test(...) on the page class catches most v5 breakage cheaply.

Gotchas and Tips

• The version number is the compatibility contract. 3.0.0 = "works with Filament v5." There are no new features listed. If you were hoping this release would fix a bug or add functionality, it won't — read the diff, not the changelog, because the changelog is two lines.
• Composer will let you get into a half-upgraded state. A single third-party Filament plugin that hasn't shipped a v5 release will block the whole upgrade. Run composer why-not filament/filament ^5.0 early to find the blocker before you start.
• Config and view caches will lie to you. After swapping versions, always php artisan optimize:clear. A stale bootstrap/cache/config.php is the #1 cause of "the plugin registered but nothing shows up."
• Re-publish assets if the package ships any. Filament v5's front-end toolchain moved; published CSS/JS from 2.x can render almost correctly, which is worse than failing outright. Delete the published asset directory and re-publish rather than layering --force on top.
• Docs URLs are unstable right now. 3.0.0 "aligned docs structure and cleanup," which means deep links in older tutorials, Stack Overflow answers, and your own bookmarks may 404 or land on the wrong page. When in doubt, browse the docs/ folder in the GitHub repo pinned to the v3.0.0 tag.
• Extension points to prefer: the plugin's fluent API (survives upgrades) > published config (survives minor upgrades, reviewed on majors) > published views (breaks on every major) > subclassing package classes (breaks without warning).
• Pin it: "lara-zeus/hades": "^3.0" and never * — you do not want a 4.0.0 that tracks a future Filament major landing in composer update unannounced.
• If you're not on Filament v5, this release is a no-op for you. Stay on ^2.0, and note that 2.0.1 will stop receiving fixes the moment the maintainer's attention moves to the v5 branch — plan the Filament upgrade rather than deferring it indefinitely.