Filament Short Url Laravel Package

Getting Started

• Install the package with Composer and let Laravel’s package discovery register the service provider. If your app does not use discovery, add the provider manually.
• Publish the package assets and run migrations:

  php artisan vendor:publish --tag=...
  php artisan migrate
  

• Open the package config file first. Focus on pixel identifiers, default event names, queue/connection settings, and any route or middleware configuration.
• Confirm where the admin/test UI is mounted (route prefix, middleware, authorization gate). The Test action is the fastest way to verify end-to-end wiring.
• First real use case: configure one pixel for a non-production environment, fire a single event from a Blade view or server-side helper, then use the pixel Test action to inspect the generated payload before enabling it in production.

Implementation Patterns

• Server-side events: use the package facade/helper to dispatch tracking events from controllers, listeners, or jobs. Keep event payload construction in a small application service so you can reuse it across webhooks, queue jobs, and tests.
• Client-side snippets: render the package’s Blade component in your layout or on specific pages. Treat the rendered snippet as the source of truth rather than hand-copying pixel code.
• Test/preview workflow: configure a pixel in the admin UI, open the Test action, and verify the escaped payload preview. Since 1.9.2 the preview renders the snippet as escaped text, so it is safe to inspect and copy without executing it in the admin page.
• Environment separation: keep test pixel IDs in .env and production IDs in production config. Use the package’s config or database-backed pixel records to avoid accidentally firing production pixels from local/staging.
• Event mapping: map application events (registration, purchase, lead) to package events in one place. This keeps naming consistent and makes it easier to add or remove pixels later.
• Queueing: dispatch tracking calls from queued jobs or listeners where possible so checkout/request latency is not affected by tracking HTTP calls.
• Testing: assert that your application dispatches the expected package events and payloads. Use the payload preview as a manual smoke test, but keep automated assertions on your own event layer.

Gotchas and Tips

• 1.9.2 fix: the Test action previously failed with View not found because components.payload-preview was missing. If you had published views or created a workaround, re-publish or merge the package view. If you override components.payload-preview, keep it compatible with the package’s escaped-output expectation.
• Escaped preview is intentional: the snippet is shown escaped so it does not execute inside the admin panel. Do not “fix” this by rendering it unescaped; copy the text into the target page source instead.
• Config cache: after changing pixel config or routes, run php artisan config:clear / config:cache as appropriate. Missing pixels after a deploy are often stale config cache.
• View namespaces: if you override package views, confirm the namespace and path. The 1.9.2 bug is a reminder that custom view publishing can drift from the package’s expected component names.
• Authorization: the Test action exposes payload details. Ensure the admin route is protected by auth and authorization middleware; do not expose it publicly.
• Consent and ad blockers: client-side pixels may be blocked or require consent gating. Server-side events are more reliable but still need consent/privacy handling.
• Debugging: if the Test action shows no payload, check that the pixel is enabled, the event name is mapped, and the package’s config is not cached. Check storage/logs/laravel.log for view-resolution errors after upgrades.
• Extension points: prefer package events, custom event classes, or a thin application service over editing vendor files. If you need custom preview markup, publish and override the component deliberately, and note it when upgrading.