Laravel Metrics Plausible Laravel Package

Product Decisions This Supports

• Analytics platform choice (build vs. buy). This package removes most of the integration cost of standardizing on Plausible: a typed client, a fluent StatsQuery builder, enums for metrics/dimensions/date ranges, and typed exceptions (AuthenticationException, RateLimitException, PlausibleException). The buy decision is really "adopt Plausible + this client" versus "build a reporting pipeline" — this makes the adoption side cost days rather than weeks.
• Where analytics lives in the product. Because the client queries stats server-side, the API key never reaches the browser and you own the UI. That unlocks in-app reporting surfaces instead of a "view analytics" link that dumps users into a third-party dashboard:
  • Content performance widgets on posts/pages (pages, entryPages, exitPages)
  • Acquisition panels (sources, channels, utm)
  • Audience panels (countries, regions, cities, devices, browsers, operatingSystems)
  • Conversion reporting (goalConversions, customEvents)
  • Live activity indicators (realtimeVisitors)
• Roadmap and prioritization evidence. aggregate and timeseries let you measure adoption of specific features, onboarding steps or campaign landing pages from inside the app, without standing up a second analytics vendor or a warehouse.
• SaaS/agency packaging. sites, site, createSite, deleteSite and the goal endpoints make analytics provisionable at signup or tenant creation, enabling white-labeled client reporting as a plan feature or upsell.
• Data residency and procurement. PLAUSIBLE_BASE_URL supports self-hosted Community Edition and private instances, which is the lever for customers or regions where GA4-style third-party tracking fails legal/security review.
• Multi-tenancy direction. Settings via spatie/laravel-settings seeded from env is a good default for single-instance use, but it is a signal to validate, not assume, per-tenant site configuration. Confirm override support before committing to a per-tenant analytics roadmap item.

When to Consider This Package

Adopt when:

• You are on Laravel 11/12/13 and PHP 8.2+, and Plausible is already chosen or shortlisted.
• You want reporting inside your own UI (admin dashboards, customer-facing reports, content performance cards) with the API key kept server-side.
• Your access pattern is read/reporting — dashboards, widgets, scheduled summaries — not high-frequency event ingestion.
• You need self-hosted or EU-resident analytics for compliance reasons.
• You can absorb early-stage dependency risk: a 1.0.0 release with a thin surface area that is easy to wrap and replace.

Look elsewhere when:

• You need event tracking or ingestion. This is a stats/reporting reader; pageviews still come from the Plausible script or a proxy.
• You need funnels, cohorts, retention, session-level paths or raw event export. Plausible is aggregate-first; that is a warehouse or product-analytics tool decision.
• You need vendor SLAs or a long support track record. Pin the version and hide it behind your own interface.
• You are on PHP < 8.2 or Laravel 10 or below — hard requirement.
• Verify plan gating first: Stats API access is tier-dependent on Plausible Cloud. Confirm your plan (or your CE build) exposes the endpoints before this becomes a dependency.
• Your self-hosted instance is on older API versions — the package mixes Stats API v2 with v1 Sites/Goals, so version drift against your instance is a real risk to test.

PM verdict: worth a spike, not a blind dependency. Adopt behind a repository/adapter interface, pin the version, cache aggressively (the presence of RateLimitException tells you 429s are expected), and treat the 1.0.0 maturity and mixed v1/v2 surface as the two risks to retire in the spike.

How to Pitch It (Stakeholders)

To executives: We can offer privacy-first, cookieless analytics — hosted in the EU or fully self-hosted — surfaced inside our own product instead of sending customers to a third-party dashboard. Integration cost is days, not a sprint, because this package supplies the client, query builder and error handling. It is a thin, replaceable wrapper, so the lock-in is low and the decision is reversible.

To engineering: A typed Laravel client over Plausible's Stats API v2 plus v1 Sites/Goals, with a fluent StatsQuery builder (metrics, dimensions, filters, ordering, pagination, imports, time labels), ready-made shortcuts for the common dimensions, enums for Metric/Dimension/DateRange/GoalType, and typed exceptions for auth, rate limiting and general failures. Config is seeded from PLAUSIBLE_API_KEY, PLAUSIBLE_SITE_ID and PLAUSIBLE_BASE_URL. Known risks: 1.0.0 maturity, mixed v1/v2 endpoints, plan-gated API access, 429s requiring caching/backoff, and read-only scope — tracking remains a front-end concern.