laravel-ga4-events maintained by eg-mohamed
Laravel GTM Events
Push events to Google Tag Manager's dataLayer and Meta Pixel from Laravel, Livewire, and plain JavaScript through one unified bridge. The package injects the tracking snippets, validates payloads, and provides browser-side debug output through console.log.
Features
- Push events to
window.dataLayerfor GTM to handle - Auto-injects the GTM container snippet
- Auto-injects the Meta Pixel base snippet
- Client-side payload validation before pushing
- Works from JavaScript, DOM custom events, and Livewire
- Blade component and directive for easy layout injection
- Console debug output
- Server-side Meta Conversions API + GA4 Measurement Protocol with browser/server deduplication
Compatibility
- PHP:
^8.3 - Laravel:
12.x,13.x
Installation
composer require eg-mohamed/laravel-ga4-events
Publish the config:
php artisan vendor:publish --tag="ga4-events-config"
Quick Start
- Set your GTM container ID in
.env:
GTM_CONTAINER_ID=GTM-XXXXXXX
GTM_EVENTS_ENABLED=true
Optional Meta Pixel support:
META_PIXEL_ID=123456789012345
META_PIXEL_INJECT_SCRIPT=true
- Inject the bridge once in your layout (before
</body>):
<x-ga4-events />
Legacy directive also works:
@ga4Events
- Push events from JavaScript:
window.GTMEvents.track('purchase_started', {
currency: 'USD',
value: 99.95,
item_count: 2,
})
GTM receives {event: 'purchase_started', currency: 'USD', value: 99.95, item_count: 2} in dataLayer. If Meta Pixel is configured, the same payload is also sent through fbq, using track for standard Meta events and trackCustom for custom ones.
Livewire Usage
$this->dispatch('gtm-event', name: 'profile_updated', params: ['section' => 'security']);
The bridge normalizes wrapped Livewire payload shapes automatically.
JavaScript API
track(name, params = {})
window.GTMEvents.track('add_to_cart', { product_id: 15, value: 150 })
dispatch(payload, source = 'manual')
window.GTMEvents.dispatch({ name: 'search', params: { term: 'sneakers' } })
DOM custom event
window.dispatchEvent(new CustomEvent('gtm:event', {
detail: { name: 'checkout_step', params: { step: 2 } },
}))
config
console.log(window.GTMEvents.config)
Payload Structure
{
"name": "event_name",
"params": {
"key": "value"
}
}
Validation rules:
namemust be a non-empty string matchingallowed_name_patternnamemust not exceedmax_event_name_lengthparamsmust be an object- param keys validated for length
- param values support
string,number,boolean,null, or nested objects - string values truncated to
max_param_value_length
Configuration
Published at config/ga4-events.php:
return [
'enabled' => (bool) env('GTM_EVENTS_ENABLED', true),
'container_id' => env('GTM_CONTAINER_ID'),
'inject_gtm_script' => (bool) env('GTM_EVENTS_INJECT_SCRIPT', true),
'meta_pixel_id' => env('META_PIXEL_ID'),
'inject_meta_pixel_script' => (bool) env('META_PIXEL_INJECT_SCRIPT', true),
'meta_pixel_event_map' => [],
'meta_pixel_standard_events' => [
'AddPaymentInfo',
'AddToCart',
'AddToWishlist',
'CompleteRegistration',
'Contact',
'CustomizeProduct',
'Donate',
'FindLocation',
'InitiateCheckout',
'Lead',
'Purchase',
'Schedule',
'Search',
'StartTrial',
'SubmitApplication',
'Subscribe',
'ViewContent',
],
'event_bus_name' => env('GTM_EVENTS_EVENT_BUS_NAME', 'gtm:event'),
'livewire_event_name' => env('GTM_EVENTS_LIVEWIRE_EVENT_NAME', 'gtm-event'),
'global_js_object' => env('GTM_EVENTS_GLOBAL_JS_OBJECT', 'GTMEvents'),
'debug' => (bool) env('GTM_EVENTS_DEBUG', false),
'strict_validation' => (bool) env('GTM_EVENTS_STRICT_VALIDATION', false),
'drop_invalid_events' => (bool) env('GTM_EVENTS_DROP_INVALID_EVENTS', true),
'max_event_name_length' => (int) env('GTM_EVENTS_MAX_EVENT_NAME_LENGTH', 40),
'max_params' => (int) env('GTM_EVENTS_MAX_PARAMS', 25),
'max_param_key_length' => (int) env('GTM_EVENTS_MAX_PARAM_KEY_LENGTH', 40),
'max_param_value_length' => (int) env('GTM_EVENTS_MAX_PARAM_VALUE_LENGTH', 100),
'max_param_nesting' => (int) env('GTM_EVENTS_MAX_PARAM_NESTING', 4),
'allowed_name_pattern' => env('GTM_EVENTS_ALLOWED_NAME_PATTERN', '/^[a-zA-Z][a-zA-Z0-9_]*$/'),
'console_prefix' => env('GTM_EVENTS_CONSOLE_PREFIX', '[GTM Events]'),
];
Meta Pixel event mapping
Map your existing event names to Meta standard events when needed:
'meta_pixel_event_map' => [
'purchase_completed' => 'Purchase',
'checkout_started' => 'InitiateCheckout',
'product_viewed' => 'ViewContent',
],
When the mapped event name matches one of meta_pixel_standard_events, the package sends it with fbq('track', ...); otherwise it falls back to fbq('trackCustom', ...).
Server-side Tracking (v2)
Send the same event from the server to the Meta Conversions API and the GA4 Measurement Protocol. Every event has an event_id, and browser and server use the same one, so Meta deduplicates them. GA4 deduplicates purchase by transaction_id.
META_PIXEL_ID=123456789012345
META_CAPI_ACCESS_TOKEN=EAAB...
META_CAPI_TEST_EVENT_CODE=TEST12345
GA4_MEASUREMENT_ID=G-XXXXXXX
GA4_API_SECRET=xxxxxxxx
GA4_MP_DEBUG=false
php artisan vendor:publish --tag="ga4-events-migrations"
php artisan migrate
Add the context middleware to every stack that serves pages (the web group, plus each Filament panel's ->middleware([...])):
$middleware->appendToGroup('web', [
\MohamedSaid\LaravelGa4Events\Http\Middleware\CaptureTrackingContext::class,
]);
Make your user model remember attribution:
use MohamedSaid\LaravelGa4Events\Concerns\HasTrackingIdentity;
use MohamedSaid\LaravelGa4Events\Contracts\ProvidesTrackingUserData;
class User extends Authenticatable implements ProvidesTrackingUserData
{
use HasTrackingIdentity;
public function trackingUserData(): array
{
return ['external_id' => $this->id, 'email' => $this->email, 'phone' => $this->phone];
}
}
Sending events
use MohamedSaid\LaravelGa4Events\Facades\LaravelGa4Events;
LaravelGa4Events::event('purchase')
->eventId('purchase-'.$order->id)
->value($order->total, 'USD')
->transactionId($order->number)
->params(['items' => [['item_id' => 'pro', 'price' => 49, 'quantity' => 1]]])
->for($order->user)
->server()
->browser()
->send();
server()queues one job per driver. Jobs are dispatched after the transaction commits and retried with backoff.browser()stores the event in the session.<x-ga4-events />fires it on the next page render, so it survives redirects.for($user)uses the user's stored attribution (fbp, fbc, ga client id, IP, user agent). It merges the live request context only when that user is the one making the request, so webhooks and admin actions never send the wrong browser data.- With no user agent known, Meta events use
action_source=system_generated.
From Livewire:
use MohamedSaid\LaravelGa4Events\Livewire\TracksEvents;
$this->trackEvent('begin_checkout', $params, server: true);
From JavaScript (needs collect_endpoint.allowed_events):
GTMEvents.track('add_to_cart', { value: 10, currency: 'USD' }, { server: true });
GTMEvents.track('purchase', params, { eventId: 'purchase-15' });
Event names
Use GA4 names. event_map translates them per destination, and false skips a destination:
'event_map' => [
'purchase' => ['meta' => 'Purchase'],
'sign_up' => ['meta' => 'CompleteRegistration'],
'exception' => ['meta' => false],
],
GA4 duplicates
GA4 does not deduplicate on event_id. When an event is also sent from the browser (browser(), trackEvent(..., server: true), the collect endpoint), the Measurement Protocol copy is skipped unless it carries a transaction_id. To change that, set ga4.mp.skip_browser_mirrored_events.
Delivery log & consent
- Each delivery is stored in
ga4_server_events(sent/failed, response code and body). The sameevent_idis never re-sent to a destination once it has been sent. - To set consent, point
consent_resolverat an invokable class that receives the request and returnsbool. When it returnsfalse, nothing is sent, no cookies are set, and the pixel is not loaded.
Debug Mode
GTM_EVENTS_DEBUG=true
Example console output:
[GTM Events] [INFO] GTM bridge initialized.
[GTM Events] [INFO] Event pushed to dataLayer from api.
[GTM Events] [ERROR] Invalid GTM payload from livewire.
Artisan Command
php artisan gtm-events:check
Validates that the package is enabled and shows the current GTM and Meta Pixel identifiers.
Skip Auto Injection
If you load the GTM snippet yourself:
GTM_EVENTS_INJECT_SCRIPT=false
The bridge still pushes events to window.dataLayer.
PHP-side Validation
use MohamedSaid\LaravelGa4Events\Facades\LaravelGa4Events;
$result = LaravelGa4Events::track('purchase_completed', ['value' => 120]);
// $result['valid'] — bool
// $result['errors'] — array of strings
// $result['name'] — sanitized name
// $result['params'] — sanitized params
Changelog
Please see CHANGELOG for information about changes.
Contributing
Please see CONTRIBUTING for contribution details.
Security
Please review our security policy for reporting vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.