- What is jeffersongoncalves/laravel-gtag and what does it do?
- It is a lightweight Laravel package that adds Google Analytics 4 tracking to your application through the Google tag (gtag.js) snippet. It provides a publishable configuration file for your GA4 measurement ID, Blade-level output for the snippet, and an enable/disable switch so tracking can differ per environment. It also ships helpers for tracking page views and custom events, and it pulls in no extra dependencies beyond Laravel itself.
- How do I install laravel-gtag with Composer?
- Install it with composer require jeffersongoncalves/laravel-gtag. The package follows standard Laravel package conventions, so its service provider is discovered automatically and no manual registration is normally needed. After installing, publish the configuration file and set your GA4 measurement ID before rendering the snippet in a layout.
- How do I configure my GA4 measurement ID for laravel-gtag?
- Publish the package config file with php artisan vendor:publish and place your Google Analytics 4 measurement ID in the published array. Most teams back that value with an environment variable so staging, production, and local can point at different GA4 properties or be turned off entirely. Keep the config file out of version-specific edits and drive it from the environment instead.
- How do I add the gtag.js snippet to a Blade view?
- The package exposes a Blade directive or component that outputs the gtag.js script tag and its initialization call for you. Add it once to your base layout, typically inside the head section, rather than repeating it in individual views. Once rendered in the layout it covers every page that extends it, including paginated and nested views.
- Can I disable Google Analytics in local, testing, or staging environments?
- Yes. The package has configurable enable/disable behaviour per environment, so you can switch tracking off in local and testing while leaving it on in production. When disabled, the gtag.js snippet is not emitted, which keeps test runs and CI pipelines from sending fake hits to your GA4 property. Drive the flag from an environment variable so you never have to edit code to change it.
- Which Laravel and PHP versions does laravel-gtag support?
- The 3.1.x line targets Laravel 9 and newer on PHP 8.1 and above, where Laravel's Vite integration and nonce helpers are available. Because the CSP nonce support depends on Vite::cspNonce(), you should confirm your Laravel version exposes that API before upgrading. Always check the composer.json constraints in the tagged release for the exact supported range.
- Does laravel-gtag support Content Security Policy nonces?
- Yes. As of 3.1.0 the package reads Laravel's Vite nonce through Vite::cspNonce() at render time and applies it to the script tags it emits. That requires your application to send a Content-Security-Policy header containing nonce-{value} and to generate the nonce before the package's tags are rendered. Applications that never set a nonce see byte-identical output, so the upgrade itself is effectively inert. Remember that a nonce only authorises inline or owned scripts, so third-party hosts still need script-src allowlisting, and cached HTML carrying a stale nonce will be blocked.
- Is laravel-gtag safe to use with Laravel Octane and long-lived workers?
- It can be, but the nonce lifecycle is the part you must verify rather than the package code. Under Octane, a nonce stored in a singleton or static property must be reset on every request, otherwise a nonce from one response can leak into another and silently weaken your policy. Confirm the nonce is generated and bound before the package renders its tags, and test under Octane rather than only under the built-in server.
- Can I track page views and custom events with laravel-gtag?
- Yes. The package provides helpers for sending page views and custom events, and the underlying gtag() function remains available for anything the helpers do not cover. Use the helpers for standard page view tracking in your layout and call gtag with an event name and parameters for interactions like signups, downloads, or checkout steps. Keep event naming consistent so your GA4 reports stay readable.
- How do I test that gtag.js and the CSP nonce are rendering correctly?
- Assert on the rendered HTML: check that the gtag.js script tag appears with your measurement ID, and that it does not appear when tracking is disabled in config. If you use CSP, also assert that the script tag carries the same nonce value as Vite::cspNonce() for that request. Finally, verify in the browser or with GA4 DebugView that hits arrive, and run a report-only CSP phase before switching to enforcement.