Filament Faq Laravel Package

Getting Started

This is the first assessment for jeffersongoncalves/filament-faq (v1.1.0). It is a Filament plugin package, so the first-hour workflow is the same as any Filament plugin: install, register the plugin on a panel, publish assets/migrations, then click through the generated resource.

1. Install

composer require jeffersongoncalves/filament-faq

Match the filament/filament major version in your composer.json — Filament plugins are tightly coupled to the panel version and a mismatch is the most common first failure.

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

use JeffersonGoncalves\FilamentFaq\FilamentFaqPlugin;

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

3. Publish and migrate

php artisan vendor:publish --tag=filament-faq-config
php artisan vendor:publish --tag=filament-faq-migrations
php artisan migrate

Check php artisan vendor:publish with no arguments first — the exact tag names are the thing most likely to differ from the convention above, and the publish list tells you what the package actually ships (config, migrations, views, translations).

First use case: after registration you get an FAQ resource in the panel where an editor creates question/answer entries with ordering and a published/draft flag. That is the core loop — everything else is presentation.

Where to look first: the resource class (...\Filament\Resources\FaqResource or similar) is the entry point. Read its form and table schemas before touching config; they tell you which columns and fields exist far faster than the config file does. Then read config/filament-faq.php for anything exposed (navigation group, ordering column, publish toggle).

Implementation Patterns

Resource-navigation integration. Let the plugin own the resource, then adjust only the surface: navigation group, sort order, and label via the plugin's fluent config or ->navigationGroup(...) on the panel. Avoid subclassing the resource unless you need new fields — that couples you to the vendor's internal schema and breaks on minor upgrades.

Content authoring vs. frontend delivery. The package manages FAQ entries in the admin panel; it is not a frontend renderer. The productive pattern is:

• Editors create/order/publish entries in Filament.
• Your application reads the same table through a small repository or model scope (published(), ordered()) and renders wherever you need — Blade component, API endpoint, or a second Filament page for a public-facing panel.

If the package ships its own model, query it directly rather than duplicating the table; a second faqs table is the classic self-inflicted migration conflict.

Seeding and fixtures. For demo or test environments, seed FAQ rows through the package model so factories and RefreshDatabase stay consistent. Do not hand-insert raw rows — if the resource relies on ordering or publish flags with defaults, raw inserts bypass them.

Locale wiring (new in 1.1.0). The 17 added locales mean the admin UI now follows app()->getLocale() for labels instead of falling back to English. Typical pattern:

// config/app.php or per-user preference
'locale' => 'de',

and, for panels that need it, ->locale(fn () => auth()->user()?->locale ?? 'en') on the panel. Because filament-faq labels are now translated, a German-locale panel produces a fully German FAQ resource with no extra work.

Multi-panel / multi-tenant. Register the plugin once per panel and keep the resource tenant-scoped in the usual way (->tenant(Team::class) and a team_id on the FAQ table). The plugin's ordering column should be scoped per tenant, so verify ordering is relative within a tenant rather than global.

Testing. Use Filament's LiveResource testing helpers against the FAQ resource (livewire(FaqResource\Pages\CreateFaq::class)->fillForm([...])->call('create')). Assert on published/draft visibility and ordering in table tests rather than rendering the admin UI.

Gotchas and Tips

Filament version pinning is the real constraint, not the package version. 1.1.0 is a translations-only release — no API or schema changes — but the package's real compatibility surface is the Filament major it tracks. Pin filament/filament deliberately and let Composer resolve the plugin; do not composer update the plugin independently of the panel.

Publish translations explicitly if you use a custom locale. The new locales ship inside the package, but if you have published translations before (--tag=filament-faq-translations or similar), the published copies win over the vendor files. After upgrading to 1.1.0, re-publish or delete lang/vendor/filament-faq/ — otherwise you keep seeing English on a locale that the release notes claim is supported. This is the single most likely reason a developer "doesn't get" the new translations.

Right-to-left locales. ar and fa are among the 17 additions. Translated labels alone do not make an admin panel RTL — the panel layout and your own custom Blade views need dir="rtl" handling. Test an Arabic panel against any custom resource pages or widgets you added, not just the FAQ CRUD screens.

zh_CN uses a region-qualified key. Set the locale as zh_CN (with the underscore and region), not zh. Filament's locale resolution is exact, so zh will fall back to English even though a Chinese translation exists.

No breaking changes in 1.1.0 — upgrade is safe. The changelog shows docs, two CI workflow standardizations, a Dependabot group bump, and the i18n feature. Nothing touches the resource schema, config keys, or public API. Treat this as a low-risk patch-level upgrade; the CI workflow changes are irrelevant at runtime.

Watch the maintainer-breadth pattern. The release credit explains that the i18n work was authored once and rolled out across this author's Filament plugins. That is a positive signal for consistency (the same locale set and translation conventions across the plugin family) but also means upstream translation quality is uniform rather than per-package curated. Spot-check de/fr/ja terminology against your domain vocabulary before shipping; if a label reads oddly, publish and override the file rather than waiting for upstream.

Debugging a missing resource. If the resource does not appear after registration: (1) confirm the plugin is on the panel that serves your route, (2) confirm the migration ran — a TableNotFoundException is usually swallowed into a generic 500, (3) run php artisan filament:optimize-clear after config or cache changes, and (4) check php artisan about for a stale config cache.

Extension points. The config file is the intended customization surface (navigation group, slug, ordering, publish behaviour). Translations and views are publishable and therefore overridable. Prefer these over forking: the package is on a 1.x line with frequent small releases, so a fork accumulates merge cost quickly for what is usually a one-line config change.