Site Stats Laravel Package

Getting Started

• Install the package into a Capell-powered Laravel app: composer require capell-app/site-stats. Note the version constraint — this is still pre-1.0 (currently 1.0.0-beta.41), so pin an explicit tag (e.g. "capell-app/site-stats": "1.0.0-beta.41") rather than floating on ^1.0@beta, because the changelog between beta.35 and beta.41 shows six tagged releases with no semver guarantee of API stability.
• Publish and review the config and migrations before running them: php artisan vendor:publish --tag="site-stats-config" and php artisan vendor:publish --tag="site-stats-migrations". Read the config file in full — it is the single best documentation of what the package actually does (tracking toggles, retention, bot filtering, storage options).
• Run php artisan migrate and confirm the stats table(s) exist and are indexed on the columns you intend to query (typically a date/timestamp column plus a URL or route identifier).
• Register the package's tracking middleware in the web group in bootstrap/app.php (Laravel 11+) or app/Http/Kernel.php. If it auto-registers, verify with php artisan route:list -v that it is actually attached to the routes you expect.
• First use case: visit a public page in a fresh session, then query the stats table directly (SELECT * FROM site_stats ORDER BY id DESC LIMIT 5) to confirm a row was written before wiring anything into a dashboard. Once writes are confirmed, add the package's Filament widget(s) to your Capell panel provider and check the numbers render.

Implementation Patterns

• Middleware-first tracking. The core pattern is a request middleware that records a visit on the way through. Treat the middleware as the extension point: most customization (excluding routes, resolving the current site, deciding what counts as a "view") is done by controlling where the middleware is attached and by supplementing it with your own middleware rather than by editing vendor code.
• Route group scoping. Attach tracking to the web group only, and explicitly exclude admin/panel routes, health checks, _ignition, telescope, and any webhook endpoints. A common layout is a dedicated trackable middleware group applied to public route files rather than blanket-applying to web.
• Filament dashboard integration. In a Capell app the natural consumption point is a Filament widget on the panel dashboard. Register the package's widget in your PanelProvider::panel() via ->widgets([...]), and keep any custom stat widgets in app/Filament/Widgets so they survive package upgrades.
• Read-through caching for hot dashboards. Aggregations over a large visits table are expensive to run on every dashboard poll. Wrap the package's query in a Cache::remember() with a short TTL (60–300s) keyed by site + date range, and invalidate on a schedule rather than per-request.
• Scheduled aggregation. For anything beyond trivial volume, add a scheduled command that rolls raw rows into daily/weekly summary tables and prunes raw data per your retention setting. This keeps the dashboard fast and makes the retention config meaningful.
• Multi-site / tenant awareness. If you run more than one Capell site, confirm how the package attributes rows to a site (column, config value, or request context) and set that context in a middleware that runs before the tracking middleware.
• Testing. In phpunit.xml set the package's tracking toggle off (or point it at a null/in-memory store) for feature tests so you don't pollute assertions or the test DB; enable it explicitly only in the tests that assert tracking behavior.

Gotchas and Tips

• Beta churn is the headline risk. Six releases between beta.35 and beta.41 with no enumerated changelog entries means you should read the compare diff (.../compare/v1.0.0-beta.35...v1.0.0-beta.41) before upgrading, and pin the exact tag in composer.json. Treat every bump as potentially breaking: config keys, table columns, and middleware names can all move pre-1.0.
• Migration drift. When upgrading betas, re-publish migrations and diff against what you already ran. Do not blindly re-run vendor:publish --force on migrations in a shared environment — it overwrites files Laravel has already recorded as run, which desynchronises the migrations table.
• Config cache staleness. After changing the package config, run php artisan config:clear (and config:cache in deploy). A cached config silently ignores your new exclusions, which is the usual cause of "it's tracking the admin panel."
• Middleware ordering. If your tracking middleware runs after StartSession, you get session-based deduplication; if it runs before, you don't. Decide deliberately. Also ensure it runs after any middleware that sets the current site/tenant, or all rows land under the default site.
• Bot and prefetch noise. Link prefetchers and crawlers inflate counts. Filter on user agent and check for Purpose: prefetch / Sec-Purpose headers, or accept that your numbers are "requests" not "humans" and label the dashboard accordingly.
• Privacy and retention. IP addresses and user agents are personal data under GDPR. Prefer storing a hashed IP (or none), and actually enforce the retention setting with a scheduled prune — a retention config that nothing reads is a compliance liability, not a feature.
• Write amplification. Synchronous inserts on every request will show up in response times under load. If the package supports a queued or buffered write path, use it; if not, consider tracking only a sampled subset or moving tracking to a lightweight middleware of your own that writes to the package's table.
• Debugging silence. If no rows appear, check in this order: middleware actually attached (route:list -v), config toggle enabled after a config clear, the route not in an exclusion list, and the DB connection the package resolves (it may use a dedicated connection from config, not your default).
• Extension points over forks. Prefer overriding via published config, container bindings, and your own Filament widgets. Forking vendor code pre-1.0 will make every subsequent beta upgrade painful.