Insights Laravel Package

Getting Started

• Install with composer require capell-app/insights. The service provider is auto-discovered; there is nothing to register manually on a standard Laravel 10/11 app.
• Publish what you need before touching code:

  php artisan vendor:publish --provider="Capell\\Insights\\InsightsServiceProvider"
  php artisan migrate
  

  Check the provider's publishes() array for the exact tags — config, migrations and views are usually published separately so you can keep migrations in sync with the package.
• Look first at: config/insights.php (tracking toggles, ignored paths, retention), the package's src/Models and src/ database/migrations (what is actually being written per request), and however the package registers its admin/dashboard surface. The migrations tell you more about behaviour than the README does.
• Version note: v1.0.48 is a patch bump. The v1.0.44 → v1.0.48 window contains only patch releases, so there are no breaking changes and no deprecations to plan around. Pin "capell-app/insights": "^1.0" and update freely.
• First real use case: wire up page-view tracking for your public site, confirm rows land in the insights table, then surface the provided dashboard widget/report in your admin panel. If you also use the Capell CMS, the widget is typically already registered by the core admin package and you just need data flowing.
• Sanity check the dependency graph with composer show capell-app/insights --tree before installing into a plain Laravel app. The package is an official Capell module and may pull in capell core contracts even when you only want the tracking layer.

Implementation Patterns

• Track via middleware, not controllers. Let the package's middleware/listener record the hit, then exclude noise through config rather than sprinkling Insights::record() calls in your actions.
• Exclusion config is the main lever. Maintain an explicit ignore list — /admin*, /horizon*, /telescope*, /api/*, health checks, asset routes — in config/insights.php so counts reflect real visitors.
• Query through the package's models/repositories. Wrap them in your own read-only service class so that if the schema shifts in a minor release you have a single place to change:

  final class TrafficReport
  {
      public function daily(string $from, string $to): Collection
      {
          return InsightsPageView::query()
              ->whereBetween('created_at', [$from, $to])
              ->selectRaw('DATE(created_at) as day, COUNT(*) as views')
              ->groupBy('day')
              ->orderBy('day')
              ->get();
      }
  }
  

• Pre-aggregate for anything user-facing. Raw per-request rows grow fast. Schedule a nightly job that rolls data into a insights_daily summary table you own, and point dashboards at that. Keep the raw table for retention-window drill-downs only.
• Multi-site / multi-locale: if you run more than one host or locale, store and group by an explicit site/locale column (or resolve per-domain config) rather than filtering by URL prefix at query time.
• Admin integration: register the widget in your panel provider or the Capell admin config. Keep the widget to a handful of aggregate queries — panels load widgets on every dashboard hit.
• Testing: disable tracking in phpunit.xml via the config flag (or by excluding * in the test environment), use RefreshDatabase, and Carbon::setTestNow() when asserting day-bucket boundaries.
• Digest reporting: a scheduled command that emails weekly totals is the highest-value integration for most teams — cheap to build on the aggregate table, and it gets stakeholders off the dashboard.

Gotchas and Tips

• Development traffic pollutes counts. Guard tracking with app()->isProduction() or a config flag, and give every developer a reset command or truncate step in their local seed.
• Bot and prefetch noise. Crawlers, Slack/Discord unfurls and browser prefetch all fire requests. Filter by user agent and by Sec-Purpose: prefetch headers, or your numbers will be 2–3× reality.
• Timezones bite. If rows are stored in UTC and you group with DATE(created_at), "today" in your dashboard is wrong for non-UTC users. Convert to the reporting timezone before bucketing, and be consistent across every query.
• Privacy / GDPR. Confirm whether IPs are stored raw and whether hashing/anonymisation is configurable. If you're EU-facing, prefer the anonymised setting and document it; consent banners don't help if the server logs before the banner is answered.
• Indexes on a growing table. Verify created_at (and your grouping column) are indexed. Add indexes in your own migration rather than editing a published package migration, so future package migrations still apply cleanly.
• Cache aggregates, not counts. Wrapping the raw COUNT(*) in Cache::remember per request just moves the load. Cache the nightly rollup and read that.
• Terse changelogs — read the diff. v1.0.48 ships only a compare link (v1.0.44…v1.0.48), which is the norm for this package. Before each bump, skim the GitHub compare view for migration files; patch releases in this series have historically included them. Always run php artisan migrate after composer update.
• Coupling to Capell. If you're outside the Capell ecosystem you'll be using a module without its natural host — expect assumptions about panel registration, admin routes and auth guards. Read the service provider's boot() before assuming it's inert.
• Extension points. Publish the views if you need to restyle the widget; publish the config for tracking rules; if the tracker is bound to an interface in the container, rebind it to add custom filtering or to forward events to a third-party analytics service instead of the DB.