feat: allow the host app to register its own management page

[ManukMinasyan]

Problem

The management config block covers slug, navigation sort/group and cluster. But Filament reads several things off the page class itself — getSubNavigation(), breadcrumbs, header actions — and config cannot reach any of them.

A consumer that wants the custom fields screen inside its own settings navigation therefore has to subclass CustomFieldsManagementPage and register the subclass on the panel. CustomFieldsPlugin::register() still adds the packaged page unconditionally, and Panel::getPages() de-duplicates by class string only — so the app ends up with two routes to the same screen, one of them unlinked.

The cluster option is not a way out: Page::getRoutePath() applies the cluster slug as a route prefix, so it moves the URL as a side effect of wanting navigation.

Solution

CustomFieldsPlugin::managementPage() — swaps the registered page rather than adding to it, so there is exactly one route either way.

CustomFieldsPlugin::make()
    ->managementPage(\App\Filament\Pages\Settings\CustomFields::class)

class CustomFields extends CustomFieldsManagementPage
{
    public static function getSlug(?Panel $panel = null): string
    {
        return 'settings/custom-fields';
    }

    public function getSubNavigation(): array { /* ... */ }
}

The class must extend CustomFieldsManagementPage (guarded with an InvalidArgumentException), so every packaged behaviour is inherited by default and a consumer overrides only what it needs. Default behaviour is unchanged when the option is not used.

Testing

tests/Feature/ManagementPageOverrideTest.php covers the default, the override, the subclass guard, and that register() puts only the override on the panel. I verified that last one is load-bearing by reverting register() to the hardcoded class — it fails.

• Package suite: 827 passed, 3 todos
• Pint and PHPStan clean

Pre-existing on 3.x, not touched here: composer test:type-coverage reports 99.4% (below the 100% gate) and Rector flags tests/Feature/ConsumerScopeHooksTest.php:469. Both reproduce with my changes stashed.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.