PHPackages                             brew-bytes/acorn-analytics - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. brew-bytes/acorn-analytics

ActivePackage[Utility & Helpers](/categories/utility)

brew-bytes/acorn-analytics
==========================

Drop-in analytics provider integration for Roots Sage themes — GTM, GA4, and Plausible with environment gating, consent integration, and a unified custom-events API.

v0.2.2(1mo ago)001MITPHPPHP >=8.1CI passing

Since May 7Pushed 1mo agoCompare

[ Source](https://github.com/Brew-Bytes/acorn-analytics)[ Packagist](https://packagist.org/packages/brew-bytes/acorn-analytics)[ Docs](https://github.com/Brew-Bytes/acorn-analytics)[ RSS](/packages/brew-bytes-acorn-analytics/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (5)Versions (6)Used By (1)

Acorn Analytics
===============

[](#acorn-analytics)

A theme-agnostic [Acorn](https://roots.io/acorn/) package that wires Google Tag Manager, Google Analytics 4, and Plausible into a [Sage](https://roots.io/sage/)theme via one config file. Drop in your IDs, ship to production — no per-project script tag boilerplate, no staging-data pollution, no manual consent plumbing.

What it does
------------

[](#what-it-does)

- **Three providers** — GTM, GA4, Plausible. Each module is independently enabled by setting its ID; missing IDs no-op silently.
- **Production-only by default** — reads Bedrock's `WP_ENV`. Configurable.
- **Skips logged-in users** — admin QA doesn't pollute prod stats.
- **Respects DNT** — clients who opt out via Do-Not-Track aren't tracked.
- **Consent-ready** — opt in via `consent.required => true` and the package defers script injection until your consent UI emits the configured JS event.
- **Unified custom-events API** — fire one `analytics:event` from anywhere in your front-end and the bridge fans it out to whichever providers happen to be enabled.

Installation
------------

[](#installation)

```
composer require brew-bytes/acorn-analytics
```

Add the IDs you want to your `.env`:

```
ANALYTICS_ENABLED=true
GTM_ID=GTM-XXXXXXX
GA4_MEASUREMENT_ID=G-XXXXXXXX
PLAUSIBLE_DOMAIN=mysite.com
```

That's it — Acorn auto-discovers the provider, defaults gate to `production`, and only providers with non-empty IDs render.

### Customizing

[](#customizing)

Publish the config:

```
wp acorn vendor:publish --tag=analytics-config
```

Then edit `config/analytics.php` to flip flags, change environments, or wire up consent integration.

Custom events
-------------

[](#custom-events)

From anywhere on the front-end:

```
window.dispatchEvent(new CustomEvent('analytics:event', {
    detail: { name: 'newsletter_signup', tier: 'free' }
}));
```

…or from Alpine:

```

```

…or from Livewire:

```
$this->dispatch('analytics:event', name: 'contact_form_submitted', form: 'sales');
```

The bridge dispatches to all enabled providers — `gtag('event', ...)` for GA4, `plausible(...)` for Plausible, `dataLayer.push(...)` for GTM — so the same event call works regardless of which provider(s) are configured.

You can also use the package's tiny PHP-free JS API:

```
window.AcornAnalytics.track('purchase', { value: 49 });
```

Automatic event tracking
------------------------

[](#automatic-event-tracking)

`acorn-analytics` ships an `auto-tracking` module that wires delegated DOM listeners for the four interactions every site ends up tracking by hand. Events flow through the same bridge as your custom events — they reach every enabled provider with no extra wiring.

Sub-featureDefaultEvent nameSample payload`phone-clicks`✅ on`phone_click``{ phone_number, link_text }``email-clicks`✅ on`email_click``{ email, link_text }``file-downloads`✅ on`file_download``{ file_url, file_extension, link_text }``scroll-depth`✅ on`scroll``{ percent_scrolled }` (one of `[25, 50, 75, 100]`)`outbound-links`❌ off`outbound_click``{ link_url, link_domain, link_text }`Outbound-link tracking defaults off because GA4's Enhanced Measurement already auto-collects outbound clicks (as `click` events with its own params). Enabling our `outbound-links` sub-feature ships a separate `outbound_click` event so the two don't collide if you happen to have both enabled.

Configure in `config/analytics.php`:

```
'auto-tracking' => [
    'enabled' => true,
    'phone-clicks' => true,
    'email-clicks' => true,
    'file-downloads' => true,
    'download-extensions' => ['pdf', 'doc', 'docx', 'zip', /* ... */],
    'scroll-depth' => true,
    'scroll-depth-thresholds' => [25, 50, 75, 100],
    'outbound-links' => false,
],
```

Set the top-level `enabled` to `false` to disable the entire module, or flip individual sub-features.

### A note on PII

[](#a-note-on-pii)

The default `phone_click` and `email_click` payloads include the actual phone number and email address from the clicked link's `href`. For a typical business site this is your **own** published contact info — already public HTML, not visitor PII, and safe to send to GA4.

If your site contains user-submitted phone/email links (vCard exports, marketplace seller profiles, etc.), those values *would* be visitor PII — and Google's [no-PII rule](https://support.google.com/analytics/answer/6366371)applies. In that case, either disable the relevant sub-feature or extend the module to redact / hash values before emit.

Cookie consent integration
--------------------------

[](#cookie-consent-integration)

Set in `config/analytics.php`:

```
'consent' => [
    'required' => true,
    'event' => 'cookie-consent:granted',  // emitted by your consent UI
],
```

When consent is required, no provider scripts inject until that event fires on `window`. Custom events dispatched before consent are buffered and flushed on acceptance.

Compatible with most consent platforms — point `event` at:

PlatformEvent nameCustom UI`cookie-consent:granted`OneTrust`OneTrustGroupsUpdated`Cookiebot`CookiebotOnAccept`Cookieyes`cookieyes:accepted`Troubleshooting
---------------

[](#troubleshooting)

**Provider scripts aren't appearing in ``.** Most likely your environment isn't in the configured `environments` list. Defaults to `['production']` only. Two common surprises:

- **Local-by-Flywheel** sites set `WP_ENVIRONMENT_TYPE=local`, not `development`. Add `'local'` to your `environments` array (or set `environments => []` to fire in every environment for testing).
- **Bedrock's `WP_ENV` constant** takes precedence if defined.

**`env()` calls return `null` on a non-Bedrock WP install.** The default `config/analytics.php` reads IDs from environment variables (`env('GA4_MEASUREMENT_ID')`etc.). On a vanilla WordPress install (no Bedrock `.env` loader), those calls return `null` and modules silently no-op. Either:

- Set the IDs as PHP constants in `wp-config.php` and read them with `defined()`, or
- Hardcode IDs directly in your published `config/analytics.php`: ```
    'google-analytics' => ['id' => 'G-XXXXXXX'],
    ```

**Provider just installed but isn't loading.** Acorn caches the package manifest at `wp-content/cache/acorn/framework/cache/packages.php`. If `composer require` was run from outside a shell that has WP-CLI DB access (common on Local-by-Flywheel), the post-autoload-dump's cache invalidation silently fails. Delete that file plus its sibling `services.php` to force a rebuild.

What it doesn't do
------------------

[](#what-it-doesnt-do)

- **Server-side tracking / Conversions API** — Plausible/Posthog server SDKs are separate packages.
- **Advertising pixels** (Meta, TikTok, LinkedIn) — for now, install GTM and add pixels there. A separate `acorn-conversion-pixels` package may follow.
- **A consent UI** — this package only listens for events. Use `acorn-cookie-consent`(forthcoming) or any third-party consent tool.

Requirements
------------

[](#requirements)

- PHP 8.1+
- Acorn 4.x or 5.x
- WordPress 6.0+

License
-------

[](#license)

MIT © Brew & Bytes

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance94

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

5

Last Release

33d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/62d079dca70ab62b930f5632778bff44e4e829d9e427c6fa1e97cb9637617021?d=identicon)[BrewandBytes-Scott](/maintainers/BrewandBytes-Scott)

---

Top Contributors

[![BrewandBytes-Scott](https://avatars.githubusercontent.com/u/190101724?v=4)](https://github.com/BrewandBytes-Scott "BrewandBytes-Scott (5 commits)")

---

Tags

acorn-packagewordpressanalyticsrootsgtmsageacornga4plausible

###  Code Quality

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/brew-bytes-acorn-analytics/health.svg)

```
[![Health](https://phpackages.com/badges/brew-bytes-acorn-analytics/health.svg)](https://phpackages.com/packages/brew-bytes-acorn-analytics)
```

###  Alternatives

[roots/bedrock

WordPress boilerplate with Composer, easier configuration, and an improved folder structure

6.5k456.5k2](/packages/roots-bedrock)[log1x/sage-directives

A set of Blade directives for use with Roots Sage.

297736.1k8](/packages/log1x-sage-directives)[log1x/pagi

A better WordPress pagination.

61112.5k](/packages/log1x-pagi)[log1x/sage-svg

A simple package for using inline SVGs in Sage 10 projects.

121573.9k5](/packages/log1x-sage-svg)[log1x/crumb

A simple WordPress breadcrumb for Sage 10.

4377.9k](/packages/log1x-crumb)[appsero/client

Appsero Client

25492.4k10](/packages/appsero-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)