Filament Pixel Laravel Package

Getting Started

Install and boot in five minutes.

composer require jeffersongoncalves/filament-pixel
php artisan vendor:publish --tag=pixel-settings-migrations
php artisan migrate

Register the plugin in the panel provider where you want tracking:

use JeffersonGoncalves\Filament\Pixel\PixelPlugin;

public function panel(Panel $panel): Panel
{
    return $panel->plugins([
        PixelPlugin::make(),
    ]);
}

That single call does two things: it hooks the Meta Pixel base snippet into PanelsRenderHook::HEAD_START, and it registers a ManagePixelSettings page (backed by spatie/laravel-settings) so a non-developer can paste the Pixel ID from the admin UI.

Where to look first, in order:

1. ManagePixelSettings page — enter your Pixel ID and toggle tracking on. Until the ID is set, the snippet injects with nothing usable in it.
2. The plugin class — confirm the fluent API surface (settingsPage(bool), and navigationGroup() per the 3.5.0 release note) against what is actually installed in vendor/.
3. The published config (config/pixel.php equivalent) — this is where per-panel or env-driven values belong if you don't want the DB settings path.
4. PixelServiceProvider — the render hook registration, if the script is not appearing where you expect.

First real use case: drop the plugin into your production panel, set the Pixel ID from the settings page, then verify in Meta Events Manager that a PageView lands. Everything else (multi-panel, consent gating, per-environment configuration) is a refinement on top of that loop.

Implementation Patterns

Script-only mode (no admin page). When the Pixel ID comes from config/env and should never be editable in the panel:

PixelPlugin::make()->settingsPage(false),

Useful for read-only production deployments and for panels where you don't want a settings surface at all. Verify the script still injects with the page disabled — the flag is named for the page, not the tracking.

Environment gating. Meta will happily ingest your local and staging traffic and skew your audience data. Register the plugin conditionally rather than relying on the settings toggle:

->plugins(array_filter([
    app()->isProduction() ? PixelPlugin::make() : null,
]))

Per-panel differentiation. The plugin is registered per panel, so each panel provider can hold a different instance and a different navigation group:

// Admin panel
PixelPlugin::make()->navigationGroup('Administration')

// Tenant panel
PixelPlugin::make()->navigationGroup('Analytics')

Be aware that the settings store is a spatie settings singleton keyed by settings class — it is effectively global, not per-panel. If two panels genuinely need different Pixel IDs, drive the ID from config and skip the settings page.

Aligning navigation with existing groups. Pass the exact visible label, and register the same group on the panel so ordering and collapse behaviour are consistent:

$panel
    ->navigationGroups(['Analytics', 'Settings'])
    ->plugins([PixelPlugin::make()->navigationGroup('Analytics')]);

Use a closure only where the label genuinely varies at request time (role, tenant, locale), and keep it allocation-light since it resolves during navigation rendering:

PixelPlugin::make()->navigationGroup(
    fn () => auth()->user()?->isAdmin() ? 'Administration' : 'Analytics'
)

Consent / GDPR. The base snippet is injected unconditionally on the panel head. For consent-gated deployments, the usual pattern is to keep the package's injection but wrap the fbq('init', ...) call behind your CMP's consent callback — either by overriding the pixel::script view or by not registering the plugin until consent is captured server-side.

Testing. Assert the hook output rather than the DB settings row:

$this->get('/admin')->assertSee('fbq(', false);

Prefer disabling the plugin entirely in the test panel provider so you don't assert on third-party markup in unrelated feature tests.

Extending. The settings page is a normal Filament page — subclass it if you need extra fields (conversion events, multiple pixel IDs) or a canAccess() policy. Keep the plugin as the single source of truth for navigation metadata and avoid also setting navigation on a subclass, or you will get confusing overrides.

Gotchas and Tips

• Docs disagree on the class name. The skill documentation uses PixelPlugin; the 3.5.0 release note refers to Plugin::make()->navigationGroup(...) and cites a filament-analytics-core 3.1 dependency. Confirm which class and which method actually exist in your installed version before writing panel code — composer show jeffersongoncalves/filament-pixel then grep the vendor/ directory.
• Migrations are not optional. Skipping php artisan vendor:publish --tag=pixel-settings-migrations leaves the settings page throwing on read. This is the single most common first-run failure.
• Hard version floors. PHP 8.2+, Laravel 11+, Filament 5.0, filament/spatie-laravel-settings-plugin ^5.0. If your panel is still on Filament 3 or 4, this package is not the drop-in you're hoping for.
• settingsPage(false) is not "disable tracking". It controls the admin page only. To stop injection, don't register the plugin, or gate it on environment.
• Livewire navigation and PageView. Filament navigates via Livewire, so full page loads are rarer than in a classic app. Confirm whether the package's navigation tracking fires on wire:navigate transitions; if it only fires on hard loads, add a Livewire::hook('navigate') or document.addEventListener('livewire:navigated', () => fbq('track', 'PageView')) to avoid undercounting. Test by navigating three pages and watching Meta Pixel Helper.
• Settings caching. spatie/laravel-settings caches; after editing the Pixel ID programmatically (seeder, deploy script) run php artisan cache:clear or save through the settings repository, otherwise stale IDs persist silently.
• Config caching. If you publish the config, remember php artisan config:cache in deploys; a env() call inside the package's config reads null once config is cached if the env var isn't present at build time.
• Debugging the script. Use view-source or the network tab to confirm fbevents.js loads, then Meta Pixel Helper for event validation. Ad blockers and Safari ITP will make local verification flaky — test in a clean profile. If nothing appears at all, check whether the page being rendered actually includes HEAD_START (error pages and non-panel routes won't).
• Closure nav groups break the whole panel if they throw. A closure that queries the tenant or user during navigation rendering has a blast radius covering the entire admin menu. Null-safe everything (Filament::getTenant()?->...) and keep it free of DB/network calls — it re-evaluates per request, per panel.
• Group label mismatch is silent. 'analytics' and 'Analytics' produce two separate headings; nothing errors, the admin UX just quietly degrades. Document the canonical group name for reviewers.
• Clear caches after any panel config change. php artisan optimize:clear plus any Filament component cache command in your deploy pipeline — navigation and hook changes are easy to miss when cached.
• Updating assertions after adopting navigationGroup(). Any test asserting the package's translated default group label will fail once you override it; assert the new label or its position instead.