Laravel
A Composer package with a Blade directive, auto-inject middleware and server-side event helpers.
The PixelFox package for Laravel renders the tag on your pages and sends the events that matter most - purchases and anything else your controllers, jobs or webhooks confirm - from the server, where no ad blocker can get in the way.
Install
The package is shipped as pixelfox-laravel.zip from your PixelFox dashboard, not on
Packagist. Extract it inside your app (it unpacks to a laravel/ folder) and add it as
a path repository:
unzip pixelfox-laravel.zip -d packages/
# → packages/laravel// composer.json
{
"repositories": [
{ "type": "path", "url": "packages/laravel" }
]
}composer require pixelfox/laravel
php artisan vendor:publish --tag=pixelfox-configThe service provider and the PixelFox facade are discovered automatically.
Add to .env:
PIXELFOX_KEY=pfx_live_YOUR_KEY
PIXELFOX_HOST=https://api.pixelfox.app| Variable | Default | Purpose |
|---|---|---|
PIXELFOX_KEY | - | Required. Your site's API key |
PIXELFOX_HOST | - | Where events are sent and where the script is loaded from. Set it to your custom ingest endpoint, e.g. https://t.yourstore.com, to serve everything from your own domain |
PIXELFOX_SCRIPT_URL | <host>/pixelfox.min.js | Load the script from a different address |
PIXELFOX_AUTO_INJECT | false | Let the middleware insert the tag into every HTML response |
PIXELFOX_TIMEOUT | 2 | Seconds to wait for a server-side send |
PIXELFOX_BUSINESS_CATEGORY | other | Drives PixelFox::recommendedEvents(). One of ecommerce_retail, entertainment_media, education, real_estate, technology, financial_services, automotive, travel, other |
Add the tag
Either place the Blade directive in your layout's <head>:
<head>
...
@pixelfoxTag
</head>…or set PIXELFOX_AUTO_INJECT=true and register the middleware to inject the tag into
every HTML response automatically:
// bootstrap/app.php (Laravel 11+)
->withMiddleware(function (Middleware $middleware) {
$middleware->web(append: [\PixelFox\Middleware\InjectPixelFoxTag::class]);
})The tag renders nothing when PIXELFOX_KEY is empty, so a local environment without a
key stays clean.
Server-side events
Fire conversion events from controllers, jobs or webhooks - immune to ad blockers, and carrying the customer's details for high-quality ad-platform matching:
use PixelFox\Facades\PixelFox;
// Anywhere after checkout completes:
PixelFox::purchase(
orderId: $order->id,
total: $order->total,
currency: 'USD',
email: $order->customer_email,
extra: ['items' => $order->lines->map(fn ($l) => [
'product_id' => $l->sku, 'name' => $l->name, 'quantity' => $l->qty, 'price' => $l->price,
])->all()],
customer: [
'first_name' => $order->first_name,
'last_name' => $order->last_name,
'phone' => $order->phone,
'city' => $order->city,
'country' => 'US',
'external_id' => $order->customer_id,
'ip' => $request->ip(), // the shopper's, not the server's
'user_agent' => $request->userAgent(),
],
);
// Or any custom event:
PixelFox::track('subscription_started', [
'plan' => 'growth',
'value' => 29,
'currency' => 'USD',
]);PixelFox::purchase() takes:
| Argument | Purpose |
|---|---|
orderId, total, currency | Required |
email | Hashed server-side before any ad platform sees it |
extra | Any further properties, such as items |
customer | The remaining match keys: first_name, last_name, phone, city, state, zip, country, external_id, plus ip and user_agent from the shopper's request so Meta can match the purchase to the browser session |
distinctId | The visitor id. When omitted the package reads the pixelfox_did cookie from the current request, so a purchase made in a controller joins the page views that led to it. Pass it yourself from a queued job or webhook, where there is no request |
Every send generates a fresh event id. If you also fire a purchase event in the browser on the confirmation page, keep only one of the two.
PixelFox::recommendedEvents() returns the conversion events recommended for your
business category - a hint for which helpers to wire up, nothing more.
Gotchas
- The middleware only injects into
text/htmlresponses that contain</head>. - Calls are fire-and-forget with a 2-second timeout - a PixelFox outage never blocks a checkout. Failures are logged to your default log channel.
- Server-side sends carry your
APP_URLas the origin, which is always allowed for your own site even when Settings → allowed origins is restricted.