Upgrading

Before upgrading

• read CHANGELOG.md
• compare the contracts reference
• confirm whether schema_version changed

Upgrade checklist

1. Review whether your host app should move from explicit registration to provider-based ->discover().
2. Keep explicit resource() and page() registration only for overrides or non-standard directories.
3. Review whether legacy resource arrays should move to the typed resource DSL.
4. Re-run host-app validation from examples/host-app/README.md.
5. Verify custom extensions against new contracts.
6. Re-test protected panel routes and JSON payload consumers.

Discovery coexistence

Older setups may still use config/flashboard.php discovery arrays:

<?php

'discovery' => [
    'resources' => [
        App\Flashboard\UsersResource::class,
    ],
    'pages' => [
        App\Flashboard\ReviewQueuePage::class,
    ],
],

This remains supported as a fallback and compatibility layer.

The new primary DX is provider-first configuration:

<?php

$this->panelConfig()
    ->path('panel')
    ->discover();

Coexistence rules:

• fallback config arrays are still read
• inline Flashboard::configure() values are merged as a compatibility layer
• provider configuration is merged last and wins over inline and fallback config
• explicit resource() and page() registrations are deduplicated with discovered classes
• withoutDiscovery() disables only auto-discovery, not explicit or fallback registrations

Provider-first direction

New host applications should prefer a generated panel provider:

php artisan flashboard:make-provider

Use inline Flashboard::configure() only when you need a transitional path in an existing host app.

Typed resource DSL migration

The preferred public API for resources is now the typed DSL:

<?php

use Pepperfm\Flashboard\Contracts\Tables\TableContract;
use Pepperfm\Flashboard\Core\Tables\Columns\BadgeColumn;
use Pepperfm\Flashboard\Core\Tables\Columns\TextColumn;

public static function table(TableContract $table): TableContract
{
    return $table->columns([
        TextColumn::make('id')
            ->label('ID')
            ->sortable(),
        BadgeColumn::make('status')
            ->label('Status')
            ->searchable(),
    ]);
}

Legacy arrays still work:

<?php

use Pepperfm\Flashboard\Contracts\Tables\TableContract;

public static function table(TableContract $table): TableContract
{
    return $table->columns([
        ['key' => 'id', 'label' => 'ID', 'sortable' => true],
        ['key' => 'status', 'label' => 'Status', 'searchable' => true],
    ]);
}

Migration rules:

• typed schema nodes are the recommended authoring style for new resources
• legacy arrays remain valid as compatibility input
• runtime payloads are normalized from both styles into the same schema contract
• detail() remains supported and infolist() is the concept-aligned alias for new resource classes
• php artisan flashboard:make-resource generates typed definitions by default

Breaking-change classes

• contract rename
• route naming change
• payload shape change
• policy mapping behavior change
• builder API signature change