Laravel Spa Analytics Laravel Package

Product Decisions This Supports

• Build vs. buy for product analytics. The package makes "own our analytics" a viable option for Laravel + SPA products: events land in your own database, queryable with SQL, with no per-event vendor pricing or third-party script on the page. This release lowers the two costs that usually kill that decision — upgrade pain and deployment staleness.
• Data ownership and residency. Because all data stays in your infrastructure, this supports decisions in regulated or privacy-sensitive contexts where sending behavioural data to a third-party SaaS is a legal or procurement blocker.
• Database capacity and isolation planning. The new spa-analytics.database.connection key is the most product-relevant addition: analytics tables can now live on a separate connection, so a growth in event volume no longer forces a decision between "analytics feature" and "primary database performance." This makes it reasonable to greenlight analytics on a product whose main DB is already under pressure — but it must be set before the first migrate, so it is a day-one architectural decision, not a later tuning knob. Decide it during the same planning cycle as the feature.
• Roadmap commitment to the Inertia/SPA path. Fixes for prefetch-cache page views and back/forward navigation mean the numbers are trustworthy for Inertia apps. If your roadmap assumes Inertia <Link prefetch> usage, the alternative (a third-party tag) would have undercounted those visits; this release closes that gap and de-risks the SPA migration itself.
• Upgrade and maintenance cost as a roadmap input. The folded migrations collapse a twelve-migration history into five create_* plus one guarded update_analytics_tables_rev_2, upgradable from any prior version in one step. Old update_analytics_* files published into your app are deleted automatically, with spa-analytics:clean-migrations for on-demand cleanup and a count surfaced in php artisan about. That converts "we're three versions behind" from a scoped ticket into a routine deploy task — a real input when weighing self-hosted against a vendor that upgrades itself.
• Deployment-pipeline decisions. The ?v=<hash> suffix on the @spaAnalytics script URL makes aggressive CDN/browser caching of the tracking script safe. This is worth an explicit line in your release process: publish assets before HTML, and key CDN caching on the query string.
• Honest accuracy budgeting. The five-second dedupe window means a response slower than five seconds can double-count one visit, and a cached replaceState visit is still missed. Both are documented limits, not defects — decide whether your p95 latency and navigation patterns make them material before committing to this as a source of truth for any metric that gets reported upward.

When to Consider This Package

Consider it when:

• The product is a Laravel app with a JS SPA front end, especially Inertia — that is the stack this release is clearly optimised for.
• You need first-party, SQL-queryable event data (page views, events, rollups) rather than a dashboard product, and you have someone who will actually write the queries.
• Traffic is moderate and predictable; you are comfortable sizing and owning the database that stores events.
• Data residency, procurement, or cookie-consent scope make a third-party tag expensive.
• You can absorb the operational commitments: running migrations, re-publishing assets on upgrade, and copying src="{{ $scriptUrl }}" into your own client-script.blade.php if you have published the package views.
• You can make the one-way decisions up front — the DB connection in particular. Set it before the first migrate; it moves no data, so retrofitting is a migration project.

Look elsewhere when:

• You need funnels, cohort analysis, attribution, or dashboards for non-technical stakeholders; this gives you tables, not an analytics product.
• You expect high event volume — event-stream scale, sub-second rollups, or retention windows beyond what a single relational database handles comfortably.
• You need cross-platform coverage (mobile apps, non-Laravel services) under one schema and one vendor-neutral event spec.
• Your team has no appetite for owning Laravel upgrades: this is a 0.8.0 package with a pre-1.0 API. This release is an upgrade that requires re-publishing migrations, re-publishing assets with --force, and editing published views. Expect a comparable step on future minors.
• You require vendor SLAs, support contracts, or an audit trail someone else maintains.
• You have a policy against tooling that writes to or deletes files in database/migrations — the automatic cleanup deletes exact filenames outside vendor/, which is safe in practice but is still automated deletion in a sensitive directory and should be cleared with whoever owns your release process.

How to Pitch It (Stakeholders)

For executives: We can own our product analytics instead of renting them — events stored in our own database, no per-event cost, no third-party script, and no vendor in the data path when privacy or procurement review comes up. The version we would adopt just got meaningfully cheaper to run: upgrades are now one step from any prior version, cleanup of stale migration files is automatic, the tracking script can no longer serve a stale copy from visitors' caches, and view counts are now correct for the Inertia front end we are moving toward. The costs are real but bounded: we own the database, the migrations, and the deploy step that publishes the script, and it is a pre-1.0 package so we budget a small upgrade task per release. It is the right call if we want SQL-level control over our own data and don't need a dashboard tool for non-technical users.

For engineering: Adopt at v0.8.0 with a three-line upgrade plan. (1) Re-publish migrations and run migrate — the schema is folded and one guarded update_analytics_tables_rev_2 upgrades any version from 0.1.0, no-op on fresh installs; the legacy update_analytics_* files we previously published are removed automatically, with spa-analytics:clean-migrations as an escape hatch and a leftover count in artisan about. (2) Decide spa-analytics.database.connection now — it routes models, raw queries, all three transactions, the MySQL/MariaDB binary check, and the migrations to a dedicated connection while Laravel's migrations table stays on the default; null preserves current behaviour, but it moves no data, so it has to be set before the first migrate. (3) Re-publish assets with --force and, if we've published the views, port src="{{ $scriptUrl }}" from the new client-script.blade.php into ours — the URL now carries a content hash read on every render, so set our CDN to key on the query string and deploy assets before HTML. The ClientScript service is container-bindable if we need to override it. Also note the tracking fixes: every SPA transition is now reported including Inertia, the server suppresses a duplicate page view for a path recorded in the last five seconds, and back/forward on Inertia pages is captured — with documented limits around >5s responses and cached replaceState visits.