fluffydiscord/google-analytics-bundle
A Symfony bundle for integrating Google Analytics into your application, providing configuration and helpers to add tracking code and monitor page views and user activity from within your Symfony project.
Architecture fit. v2.2.0 shifts the package from a documented fetch wrapper to a Stimulus-driven bridge: PHP collects analytics events on the Live Component response, data_layer_controller.js hooks render:started, and pushes the collected payloads into the GTM/GA dataLayer. This is a clean fit for a Laravel + Livewire v3 + Stimulus stack, where the client lifecycle is already event-driven and the head bootstrap is server-rendered. It is a poorer fit for stacks without Stimulus (plain Blade + inline <script>, Alpine-only, Inertia/Vue/React SPAs) and for non-Livewire AJAX flows that now must call pushAnalyticsEvents(response) explicitly.
Integration feasibility. Moderate. Three surfaces must line up: (1) the Blade helper google_analytics_head() rendering data-controller on the dataLayer bootstrap element, (2) the Stimulus identifier registered in the app matching stimulus_controller_name, and (3) the compiled assets under assets/src/* reaching the public bundle (Vite build or importmap pin). The head-rendered data-controller attribute introduces a load-order dependency: Stimulus must be started after the bootstrap element exists, otherwise the controller never connects and events vanish without an error. CSP nonces on the inline head snippet and JS-disabled/SSR paths need explicit decisions.
Technical risk. The release note says the Stimulus bridge replaces the documented fetch wrapper — treat this as breaking. Any shop code, internal docs, or theme snippets calling the old wrapper will silently stop emitting analytics (no exception, no console error, just missing dataLayer pushes). Secondary risks: double-pushing when the automatic Live Component hook and a manual pushAnalyticsEvents(response) call apply to the same response; pushes firing on validation-failed or no-op renders and polluting funnel steps; analytics:event CustomEvent name collisions with the shop's own listeners; PII leaking into the dataLayer because the payload contract is now assembled server-side and pushed wholesale.
Key questions. Is the fetch wrapper removed outright or aliased/deprecated with a shim? Is there a migration guide and a change note in the changelog? Does the controller dedupe when a component re-renders (validation errors, polling, infinite scroll)? Is the push ordered before or after the DOM patch? What is the version support matrix (Laravel 10/11, Livewire v2 vs v3)? What happens when dataLayer is undefined or GTM is not loaded? Is Google Consent Mode v2 handled, and who owns the consent gate? What is the documented shape of the analytics:event payload so downstream consumers can rely on it?
Stack fit. Confirm the target app is Laravel with Livewire v3 (render:started is a v3-era hook), Stimulus as the controller runtime, and GTM/GA4 as the destination. If the shop is Alpine-only or uses inline scripts in Blade, budget for adding Stimulus before adopting — otherwise this release is a step backwards.
Migration path. Inventory every use of the old fetch wrapper and every place analytics events are currently emitted. For Live Components, delete the manual wiring and let data_layer_controller.js do the work. For the shop's own AJAX calls, replace the wrapper with pushAnalyticsEvents(response) and assert the response body still carries the event collection in the shape the helper expects. Update the layout to call google_analytics_head() and set stimulus_controller_name to the identifier actually registered in app/javascript/controllers/index.js (or the importmap equivalent). Roll out against a staging GTM container with Preview/Debug before touching production.
Compatibility. Verify the published assets land in the build output and are cache-busted on deploy; a stale hashed bundle is the most likely cause of "controller not found." Check whether the package expects importmap pins or a Vite entry, and whether the README documents registering the controller. Confirm CSP headers permit the head snippet. Confirm the Livewire version constraint in composer.json matches the app. For apps still on the previous release, pin 2.1.x until the migration is validated.
Sequencing. (1) Inventory analytics call sites and fetch-wrapper usages. (2) Upgrade in staging, register the Stimulus controller, set the config key. (3) Validate event parity in GTM Preview: event names, parameter names/types, ordering relative to page_view, and single-fire per user action. (4) Explicitly test validation-failure renders, pagination/infinite scroll, and modal/drawer components for duplicate or spurious pushes. (5) Canary to production on a low-traffic segment. (6) Remove legacy wrapper code and update internal docs. (7) Publish the analytics:event payload contract for anyone building custom listeners.
Maintenance. The JS surface is small (two files), but the package now sits on two upstream contracts — Livewire's render:started hook and Stimulus's controller lifecycle — either of which can churn on a major upgrade. The stimulus_controller_name config key is a silent-failure footgun: a typo produces zero analytics with no error. Track upstream release notes for both dependencies, not just this package.
Support. Expect a spike in "analytics stopped working" tickets immediately after upgrade, mostly from the removed fetch wrapper and from controller-name mismatches. Add a debug escape hatch — a config flag that logs when dataLayer is missing or when a push is skipped — and document it. Publish a short migration note in the repo; the release note as written is not sufficient for a shop developer to act on.
Scaling. Runtime cost is negligible per push. Two things to watch: the number of Live Components on a page scales the number of render:started listeners, and long-lived SPA sessions grow the dataLayer array unbounded, which slows GTM tag evaluation. If the shop has many custom analytics:event listeners attached to document, audit for leaks on Turbo/Livewire navigation.
Failure modes.
stimulus_controller_name mismatch → zero events, silently.dataLayer undefined (GTM blocked, consent denied, script order) → throw or silent no-op depending on implementation; confirm which.pushAnalyticsEvents call both fire on one response.data-controller, same silent failure as above.Ramp-up. Low for a Laravel dev already fluent in Livewire and a bundled asset pipeline; moderate for teams historically using inline <script> blocks in Blade, who must learn Stimulus registration and the build step. Budget roughly one sprint for migration plus GTM-debug QA, and designate one owner for the analytics event contract so the server-side payload shape does not drift from what the JS bridge and the shop's custom listeners expect.
How can I help you explore Laravel packages today?