Rhea Laravel Package

Getting Started

Rhea is part of the Lara Zeus suite of Filament plugins. The v2.1.0 release is a maintenance release: the only functional change is Laravel 11 support (PR #24). The other two entries are Dependabot bumps to CI actions (ramsey/composer-install 2→3, dependabot/fetch-metadata 1.6→2.0), which do not affect the shipped package. No breaking changes, no deprecations, no migration changes — a composer update lara-zeus/rhea from v2.0.4 is safe.

Minimal setup:

composer require lara-zeus/rhea
php artisan vendor:publish --tag=zeus-rhea-config   # config
php artisan vendor:publish --tag=zeus-rhea-migrations
php artisan migrate

Register the plugin on the panel that should expose it:

// app/Providers/Filament/AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(\LaraZeus\Rhea\RheaPlugin::make());
}

Where to look first:

1. vendor/lara-zeus/rhea/config/ — the published config is the fastest way to see which features (per-panel, frontend rendering, uploads) are toggled on by default.
2. vendor/lara-zeus/rhea/src/RheaPlugin.php — shows what the plugin registers (resources, pages, migrations), which tells you exactly what will appear in the panel.
3. vendor/lara-zeus/rhea/resources/views/ — the Blade surface area you can publish and override.

First use case: install it, boot the panel, confirm the new navigation group item appears, then build one form end-to-end in the UI before touching config. That single loop (build → save → render → submit) surfaces 90% of setup problems (storage disk, panel scoping, view publishing) immediately.

Implementation Patterns

Plugin-per-panel. Rhea registers Filament resources, so it must be attached to each panel that needs it. If you have an AdminPanelProvider and a AppPanelProvider, register the plugin in both — or only the app panel if the builder UI is for end users and the admin panel handles moderation. Config keys are typically per-panel-id, so keep panel IDs stable; renaming a panel ID silently drops its Rhea config.

Build in the panel, render in your app. The usual workflow is: admins author the form definition through the Filament UI, the definition is persisted as a structured record, and your application renders it in a controller/Blade view for end users. Keep the rendering path thin — resolve the form by slug or ID and hand it to the package's render entry point rather than reimplementing field logic:

// routes/web.php
Route::get('/forms/{slug}', function (string $slug) {
    $form = \LaraZeus\Rhea\Models\Form::where('slug', $slug)->firstOrFail();

    return view('forms.show', compact('form'));
});

Keep submissions in your own layer when they matter. Treat the package's storage as the form definition and short-term submission record; if submissions feed reporting, exports, or downstream jobs, mirror them into an app-owned model via a model observer or a FormSubmitted-style event. This keeps you insulated from schema changes on minor upgrades.

Custom field types are the main extension point. Extend rather than fork. Register additional field components in your own service provider and point Rhea at them; forking the package to add a field type guarantees a painful merge conflict on the next release like this one.

Config caching in CI. Because behaviour is config-driven, run php artisan config:cache in deploy pipelines after publishing config, and php artisan filament:cache-components (or optimize) so resources/pages are resolved from cache. In local dev, php artisan optimize:clear after any config edit.

Testing. Filament resources are Livewire components — test them with Livewire::test(FormResource\Pages\CreateForm::class)->fillForm([...])->call('create'). For rendering, assert on the resolved form object and the presence of field names rather than on markup.

Upgrade path for this release. Update the composer constraint to allow Laravel 11 if you're pinned, and confirm every other Lara Zeus package and Filament plugin in the project is also Laravel 11-ready — a mixed set is the most common failure mode when moving to Laravel 11:

composer require lara-zeus/rhea:^2.1 --with-all-dependencies
php artisan migrate   # no-op, but safe
php artisan optimize:clear

Gotchas and Tips

• This release is almost entirely CI. Two of the three changes are Dependabot bumps to GitHub Actions. If you're reading the changelog looking for behaviour changes, the only one is the Laravel 11 constraint widening. Don't schedule a regression pass for it; just run your existing test suite.
• Laravel 11 changed the skeleton, not the package. Laravel 11 slimmed the default config directory and moved several framework defaults. If Rhea's published config references keys you no longer have locally, publish it fresh rather than diffing against the v10 version — and never assume an existing published config is still complete after a major Laravel bump.
• Register the plugin before running migrations. The migration tag ships with the package; if you migrate before publishing and before the plugin/ServiceProvider is loaded (e.g. in a package-discovery-cached environment), you get silent missing tables and confusing "class not found" errors on first page load.
• Stale package discovery. After composer update, if the plugin's resources don't appear, run php artisan package:discover and php artisan filament:upgrade. On shared hosting with a committed bootstrap/cache/packages.php, the cached discovery file is a frequent culprit.
• Assets and views. If you've published views (--tag=zeus-rhea-views), they win over the package's. After a version bump, compare your published copies against vendor/ — an old published view referencing a changed component can break rendering without any error in the package itself.
• Tailwind content paths. If you compile your own theme, the package's views must be in your content globs (./vendor/lara-zeus/rhea/resources/views/**/*.blade.php), otherwise the builder UI renders unstyled and looks broken when it isn't.
• Composer constraint conflicts. The Laravel 11 support lands as a widened illuminate/* constraint. If you're stuck on an older lara-zeus/* sibling package that hasn't shipped the same widening, composer will resolve back to v2.0.x without an obvious error — check composer show lara-zeus/rhea after updating to confirm you actually got 2.1.0.
• Debugging rendering issues. Most "the form renders wrong" reports trace to the panel ID or the config key being read, not to the form definition. Log the resolved config array once at boot; it's faster than stepping through the render pipeline.
• Extension points, in order of safety: config → published views → custom field components → events/observers → forking (never).