Cookieless Analytics Bundle Laravel Package

Getting Started

This is a pre-1.0 package (0.4.x), so treat the first hour as reconnaissance rather than a copy-paste install — the public surface is still shifting between minor releases.

1. Install and publish. composer require jackfumanchu/cookieless-analytics-bundle, then publish the config and any migrations via the package's vendor:publish tags. Read the published config in full before running migrations; the storage driver and retention settings are the two decisions that are painful to reverse later.
2. Where to look first. Open the package's src/ root and read, in order: the service provider (what gets bound, what middleware or routes are registered, whether the dashboard is auto-enabled), the config file (every knob), and the console commands (retention/pruning, backfill, aggregation). That trio tells you 80% of the operational story.
3. First real use case. Wire up server-side pageview collection on your highest-traffic, lowest-risk route group — typically your public marketing pages — before touching authenticated areas. Cookieless tracking is attractive precisely because it avoids a consent banner, but that argument only holds if you are not collecting anything that re-identifies a person. Verify that in the source, don't assume it.
4. Validate the pipeline end-to-end with a request, then a query or dashboard read, on the same day. Silent failures (a missing middleware alias, a queue worker not running) are the most common first-day confusion.

Because v0.4.0 shipped with only a changelog link and no prose, diff v0.3.6...v0.4.0 yourself before upgrading an existing install, and pin to an exact version in composer.json rather than a caret constraint while the package is in the 0.x series.

Implementation Patterns

• Middleware over JavaScript. The value of this class of package is that collection happens server-side, so ad blockers and script-blocking browsers don't erase your data. Prefer the package's middleware on route groups over any client-side snippet, and register it on the groups that matter rather than globally — global registration inflates volume with health checks, asset routes, and API noise.
• Queue the writes. Enqueue the recording step if the package supports it, or wrap it in a terminate()-style after-response hook. Analytics should never sit in the critical path of a user request.
• Filter at the boundary, not in the report. Bot and internal-traffic exclusion belongs in config or a middleware rule, not in your dashboard queries. Keep one source of truth for "what counts as a pageview" so the numbers stay reconcilable across views.
• Retention as a scheduled command. Tie the package's pruning command to Schedule::daily() with onOneServer() if you run multiple app servers. Cookieless rollups still accumulate; unbounded growth is the usual second-quarter surprise.
• Aggregate for anything dashboard-facing. Raw hit tables are fine for a week of debugging and terrible for a year of reporting. If the package offers a rollup/aggregation command, schedule it and query the aggregates.
• Wrap it behind your own interface. Define a small AnalyticsRecorder contract in your app, with an adapter around the package. Given the 0.x versioning, this is the difference between a one-file upgrade and a scattered refactor when a minor release renames things.
• Test with an in-memory or array driver. Point the package at a non-production sink in your test suite so feature tests don't pollute real metrics, and assert on your adapter rather than on package internals.

Gotchas and Tips

• 0.x means minor versions can break. 0.3.6 → 0.4.0 is a minor bump by semver's pre-1.0 convention, which explicitly permits breaking changes. Read the compare diff; the changelog link alone is not a substitute.
• Cookieless ≠ automatically compliant. No cookies means no cookie banner under most regimes, but IP addresses, user agents, and referrers are still personal data in many jurisdictions. Check whether the package truncates or hashes IPs, and whether that is configurable. This is the single most important thing to verify in the source.
• Config cache traps. After changing package config, php artisan config:clear. Package configs merged at boot behave differently from published ones, and a stale cached config is the classic "my setting is ignored" bug.
• Route and middleware collisions. Auto-registered dashboard routes frequently clash with your own /admin or /analytics paths, and the dashboard is often the least-guarded surface in the package. Check the authorization gate before enabling it outside local.
• Pruning without a backup is irreversible. Run the retention command against a staging copy first and confirm what it deletes — some implementations drop aggregates as well as raw rows.
• Extension points to prefer: the storage driver binding, the filtering/exclusion hook, and the event or job dispatched after a hit is recorded. Hook there rather than subclassing internals; those three seams are the most likely to survive a version bump.
• Debugging a flat dashboard: check the middleware is actually in the resolved route's middleware list (php artisan route:list -v), then the queue worker, then the storage driver — in that order. It is almost always one of those three.