Filament Forge Insights Laravel Package

Getting Started

This is the initial v1.0.0 tag and the release notes carry no changelog detail, so treat the public API as newly stabilised and confirm the exact surface area against the source before building on it.

Minimal setup:

composer require prodstarter/filament-forge-insights
php artisan vendor:publish --tag="filament-forge-insights-config"

Add a Forge API token (create one in Forge under your profile → API, scoped to the organisations you want to surface):

FORGE_API_TOKEN=your-token-here

Register the plugin on the panel you want it to appear in:

// app/Providers/Filament/AdminPanelProvider.php
public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugin(ForgeInsightsPlugin::make());
}

Look here first, in this order:

1. composer.json — confirm the filament/filament constraint (^3.0 vs ^4.0) and the PHP floor before anything else. A v1.0.0 of a Filament plugin usually pins one major.
2. config/filament-forge-insights.php — token key, cache TTL, organisation filter, navigation settings.
3. src/ForgeInsightsPlugin.php — the fluent make() config: navigation group/label, which pages or widgets are registered, and any ->authorize()/->visible() hooks.
4. The Pages/, Resources/, or Widgets/ directories — this tells you immediately whether the package is dashboard-widget-shaped or CRUD-resource-shaped, which decides how you integrate it.

The fastest first use case is a read-only dashboard widget: register the plugin, drop ForgeInsightsPlugin::make() into a non-production panel, and confirm server/site status renders for one organisation. Don't wire deploy actions or webhooks until you've validated token scope and caching behaviour.

Implementation Patterns

Panel scoping. Most Filament plugins of this shape register pages into the panel they're attached to. If you run separate admin and tenant panels, register the plugin only where it belongs — a plugin registering Resources globally via a service provider is harder to unwind than one registered per panel.

Cache-first reads. Forge data is remote and slow. Wrap every read in Cache::remember() keyed by organisation + resource, with a short TTL (60–300s) for status and a longer one for static metadata. If the package ships its own cache layer, configure it via the config file rather than adding a second one on top.

Webhook-driven invalidation. Pair the plugin's cached view with a Forge deployment webhook hitting a small route in your app that busts the relevant cache keys. This gives near-real-time deployment status without polling the API on every page load.

// routes/api.php
Route::post('/forge/deploy-hook', function (Request $request) {
    Cache::forget("forge:site:{$request->input('site.id')}");
    return response()->noContent();
});

Authorization before exposure. Forge data leaks infrastructure detail — IPs, repo names, env var names. Gate the plugin's pages behind a policy or ->visible(fn () => Gate::allows('viewForgeInsights')) and keep the plugin off any panel with broader access than your ops team.

Multi-organisation setups. If your token can see several Forge organisations, prefer an explicit allow-list in config over "show everything". A config-driven organisations array is easier to reason about than filtering inside widgets.

Extension via your own pages. Rather than forking, add your own Filament page that injects the package's service/API client and renders a custom view. Keeps you on the upgrade path.

Gotchas and Tips

• Forge API rate limits are per-minute and unforgiving. A dashboard with several widgets each making independent calls will burn through the budget on a single page load. Verify the package caches by default; if it doesn't, wrap it. This is the single most likely production issue with a v1.0.0 release.
• Token scope, not just token validity. A token scoped to one organisation will 403 or return empty for others. Symptom is usually silent empty tables rather than an error — check storage/logs/laravel.log for swallowed HTTP exceptions.
• Never commit the token. Put it in .env and reference it via config() only. If the config file ships with a hardcoded default, remove it.
• Livewire polling is a hidden cost. If widgets use protected static ?string $pollingInterval, each tick is an API call per user per widget. Set it to something sane (30s+) or null and refresh on demand.
• Filament major-version drift. Filament v3 → v4 changed the schema/form APIs significantly. A package tagged v1.0.0 against v3 will emit confusing errors under v4. Pin Filament in composer.json and read the package's constraint carefully.
• Timezone mismatch. Forge servers report in their own timezone; deployment timestamps rendered raw will look wrong to operators. Render with ->timezone(config('app.timezone')) or set the display timezone in config.
• Testing. Use Http::fake() with captured Forge API fixtures so your test suite never touches the real API. If the package ships a facade or client class, bind a fake in the container instead — cleaner than URL-matching.
• Publish tags. Run php artisan vendor:publish interactively once to see all available tags; a config-only publish will silently skip any migrations or views the package expects.
• Upgrade posture. With no changelog in the v1.0.0 notes, watch the repo's commit history for the first few patch tags — early 1.x releases of Filament plugins frequently adjust config keys. Pin to ^1.0 but review diffs on minor bumps until the API settles.