eg-mohamed / laravel-ga4-events
A Laravel package to push events to Google Tag Manager dataLayer and Meta Pixel from PHP, Livewire, and JavaScript.
Fund package maintenance!
Requires
- php: ^8.3
- illuminate/support: ^12.0||^13.0
- spatie/laravel-package-tools: ^1.93
Requires (Dev)
- laravel/pint: ^1.29
- nunomaduro/collision: ^8.9.1
- orchestra/testbench: ^8.0||^9.0||^10.0||^11.0
- pestphp/pest: ^4.4.3
- pestphp/pest-plugin-arch: ^4.0
- pestphp/pest-plugin-laravel: ^4.1
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
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]; } }
OpenAI Ads (Conversions API + Measurement Pixel)
Create a Pixel ID and API key in the Conversions tab of OpenAI Ads Manager:
OPENAI_PIXEL_ID=px_... OPENAI_CAPI_API_KEY=... OPENAI_CAPI_VALIDATE_ONLY=false OPENAI_SEND_CUSTOM_EVENTS=false OPENAI_PIXEL_DEBUG=false
The oaiq pixel is injected once consent is granted. Mapped events go to both the pixel and the Conversions API with the same event_id, so OpenAI deduplicates them. oppref and __obref are captured by CaptureTrackingContext and forwarded on server events. To map a custom event, add an openai key to its event_map entry: a standard type such as lead_created, or a custom name. Set it to false to skip OpenAI for that event.
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.