Filament Rankforge Lite Laravel Package

Getting Started

Three steps to a working setup:

1. Install and migrate — the package ships its own rankforge_meta migration, so run php artisan migrate after composer require. No publish step is mentioned for config; check config/rankforge.php only if you need to change defaults (locales, score thresholds, preview host).
2. Add the trait to any model that needs SEO: use HasSeo; — nothing else. The score column and meta row are managed for you on every save(), including queued jobs, seeders and Tinker, not just Filament.
3. Render the tags in your layout <head>: <x-rankforge::tags /> or the shorthand @rankforge. That is the first end-to-end use case — a blog post with an admin form, a live score, and correct meta output — and it should take under ten minutes.

Where to look first: the SeoFields form section (if you use Filament, this is the whole authoring UI), then config/rankforge.php for locale and threshold tuning. Ignore the analysis internals until you have a score showing up.

Implementation Patterns

Filament resource wiring. Drop SeoFields::make() into the resource schema as its own section, usually last and collapsed:

use Rankforge\Filament\Sections\SeoFields;

public static function form(Form $form): Form
{
    return $form->schema([
        // ...content fields...
        SeoFields::make(),
    ]);
}

The section carries focus/related keyphrases, meta title and description, canonical, robots, and Open Graph fields, plus the live analysis panel. Treat it as a single unit — it is designed to sit beside your content fields so the analysis reacts as the editor types.

Table columns. SeoScoreColumn::make('seo_score') (or whatever accessor the trait exposes) is sortable and colour-coded. Use it for editorial triage: sort ascending to surface the worst-scoring published content, which is the highest-value daily workflow this package enables.

Rendering. A single @rankforge in layouts/app.blade.php covers the common case. For non-Blade or API-driven front ends, resolve the tags programmatically from the model's meta relation and inject them yourself.

Coexistence with ralphjsmit/laravel-seo. The release explicitly states no trait boot-method collision, so both traits can live on the same model. If you are migrating, run them in parallel first: keep laravel-seo rendering until RankForge output is verified, then swap the Blade directive. Because table, migration and config keys match RankForge, an in-place upgrade needs no content migration.

Editing outside Filament. Because the score syncs on every save, programmatic content updates (imports, API writes, bulk jobs) keep scores honest. That makes scheduled re-scoring viable: a nightly job that touches updated_at on stale posts will refresh scores without an admin opening a form.

Gotchas and Tips

• Score sync runs on save, not on render. If you change analysis rules or thresholds in config, existing rows keep their old score until saved again. Plan a backfill command that saves each model once after any config change.
• The analysis is an editor aid, not a gate. A green score does not mean the page ranks. Use the 22 checks as a checklist for the boring stuff (title length, description presence, heading structure) and let humans judge intent.
• 22 checks across 6 languages means language-dependent checks behave differently per locale. For multilingual sites, verify the panel actually detects the right language from the record — a mis-set locale produces misleading readability scores, which is a confusing bug to chase.
• SERP and social previews are approximations. The desktop/mobile SERP preview and the Facebook/X/LinkedIn cards are useful for catching truncation, not for pixel-accurate verification. Still spot-check real shares before launch.
• Open Graph image handling is the usual source of broken cards: relative paths, storage disks that are not publicly reachable, and missing absolute URLs. Confirm the generated tag is an absolute, publicly fetchable URL on production, not just on localhost.
• Robots and canonical are high-blast-radius fields. Exposing them in the admin means an editor can accidentally noindex a money page. Consider restricting those fields by policy/role, or at minimum audit them before deploys.
• hreflang output depends on correct locale configuration. If you run multiple locales, verify the emitted hreflang set is reciprocal across the whole locale group — half-configured hreflang is worse than none.
• Extension points are the config file and the Blade component's view. If your tag output needs custom markup (extra schema.org JSON-LD, for example), publish/override the component view rather than post-processing the rendered string.
• Do not add a second SEO trait with a conflicting boot prefix. The claim is specific to ralphjsmit/laravel-seo; any other package that boots a trait method with the same name will still collide. Test in a branch before assuming compatibility.