Filament Cms Github Laravel Package

Getting Started

What changed in v5.0.0: the package now targets Filament v5 and Laravel 12/13 on PHP 8.2+. This is a major-version bump aligned with Filament's own major release, so treat it as a fresh integration rather than a patch upgrade.

1. Check your stack first. You need PHP 8.2+ (the CI matrix validates 8.3/8.4 — prefer 8.3+), Laravel 12 or 13, and Filament v5. If you are still on Filament v3/v4 or Laravel 10/11, stay on the previous 4.x line.
2. Install:

   composer require tomatophp/filament-cms:^5.0
   

3. Run the install command and migrate. v5 adds test coverage around the install command, so it remains the supported entry point for publishing config/migrations and seeding defaults:

   php artisan filament-cms:install
   php artisan migrate
   

4. Register the plugin in your panel provider (app/Providers/Filament/AdminPanelProvider.php):

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugin(FilamentCmsPlugin::make());
   }
   

5. First use case: open the panel and create a post/page from the CMS resources. That single loop — author in Filament, read the Eloquent model in your frontend — is the core of the package. Everything else (imports, SEO fields, taxonomies) is layered on top.

Where to look first: the published config/filament-cms.php (content types, route/prefix settings), the package's src/Models (what you'll query from your app), and the migrations (schema you'll be extending).

Implementation Patterns

Plugin registration is the extension surface. Almost every feature toggle in v5 is a fluent call on the plugin object, not a config key. The release notes call out one explicitly:

$panel->plugin(
    FilamentCmsPlugin::make()
        ->allowContentImport()   // reveals the GitHub import action
);

Adopt the habit of configuring the plugin in the panel provider and keeping config/filament-cms.php for values you want env-driven.

Content import workflow. With allowContentImport() enabled, an import action appears on the relevant CMS resource pages and pulls content from GitHub. Use it for bootstrapping a site from a repo of markdown/JSON content, or for syncing editorial content maintained outside the CMS. Because it can overwrite or duplicate records, gate it behind authorization in production panels and run it first against a staging database.

Multi-panel setups. A common pattern is a Content panel for editors (plugin enabled, resources visible) and a separate Admin panel where you expose only a subset via shouldRegisterNavigation() / policy scoping. Since the plugin registers resources globally, restrict with policies rather than by disabling the plugin.

Extending rather than editing. Subclass the shipped resources and models and re-register them, or use Filament's resource getPages() overrides, instead of editing vendor files. For frontend, query the models directly in your controllers/routes — the CMS is a data layer with an admin UI, not a frontend framework.

Testing with the shipped factories (new in v5). The package now ships model factories, which removes the biggest friction point in testing CMS-dependent features:

use TomatoPHP\FilamentCms\Models\Post;

it('renders a cms post', function () {
    $post = Post::factory()->create(['published_at' => now()]);

    $this->get($post->url)->assertOk();
});

If your app's Factory::guessFactoryNamesUsing or HasFactory::newFactory() assumes Database\Factories, point those models at the package namespace, or set the $factory property on your subclass.

Panel-level integration tips.

• Register the plugin after any custom resources so navigation ordering is predictable.
• Publish migrations once, then treat them as app-owned; don't re-publish on every upgrade.
• If you need a distinct content model (e.g. Article), extend the base model and swap it via the config/model binding rather than forking.

Gotchas and Tips

This is a lockstep upgrade, not an isolated one. Filament v5 changes (schema/form API, panel configuration, action APIs) will break your own resources at the same time as this package's. Upgrade Filament, this package, and any other tomatophp/filament-* plugins in one commit, and follow Filament's own upgrade guide alongside this one. A partially upgraded set of Tomato plugins is the most likely source of confusing runtime errors.

The import action "doesn't exist" until you opt in. If you upgraded and can't find GitHub import, it's because allowContentImport() is off by default — the release notes explicitly flag the README change. Check the plugin chain in your panel provider before assuming a regression.

Missing GitHub credentials fail silently-ish. Import needs a token (and a repo reference) configured; without it the action will error on execution rather than at boot. Verify credentials in a non-production environment and confirm outbound HTTP isn't blocked by your host.

Migrations after a major bump. If you previously published migrations, compare them against v5's originals — a major release may add columns or indexes. Don't blindly re-publish over edited files; diff first, then add a new migration for the delta.

Config caching hides plugin changes. Filament panel configuration is code, but the CMS config is cacheable. After changing env-driven CMS values, run php artisan config:clear; in production, config:cache on deploy.

PHP version mismatch. The composer constraint allows 8.2, but CI only exercises 8.3/8.4. On PHP 8.2 you're outside the tested matrix — fine for now, but budget for moving to 8.3+.

Debugging checklist for "resource missing / 500 on panel load":

1. composer show tomatophp/filament-cms — confirm 5.x, not a stale 4.x resolution.
2. Confirm Filament is v5 (composer show filament/filament).
3. php artisan about for Laravel version and cached config state.
4. php artisan filament:optimize-clear (or filament:clear-cached-components) after upgrading — stale Filament component caches are a classic post-upgrade failure.
5. Check that published views/assets are current if you've published them; v5 asset changes may require re-publishing.

Extension points worth knowing: plugin fluent setters (features/toggles), policies for per-panel visibility, model subclassing plus config binding for custom content types, and the shipped factories for test fixtures. Prefer these over touching vendor code so future major bumps stay cheap.