Laravel Glimpse Laravel Package

Getting Started

laravel-glimpse is a lightweight page-view/analytics package. This release (v0.5.1) is a patch release — three bug fixes, no new API surface and no breaking changes — so it's a safe in-place upgrade from v0.5.0. If you are adopting the package now, start on ≥ v0.5.1 to avoid the schema and scheduler issues described below.

Minimal steps

1. Install and publish:

   composer require pascal-kleindienst/laravel-glimpse
   php artisan vendor:publish --tag="glimpse-config"
   php artisan vendor:publish --tag="glimpse-migrations"
   php artisan migrate
   

   Confirm the published tags and namespace against the package README — the vendor name is derived from the repo owner, so let composer show be the source of truth.
2. Verify the schema landed: you should see a glimpse_page_views table whose indexes were created cleanly. If the migration errored with an index-length or duplicate-index error, you are on a stale published migration (see Gotchas).
3. Confirm the scheduler wiring: run php artisan schedule:list. As of v0.5.1 the package's maintenance commands are auto-registered, so there should be glimpse:* entries without you adding anything to routes/console.php or Kernel::schedule().
4. First use case: hit any front-end route, then confirm a row appears in glimpse_page_views. Once you can see raw rows, start reading them through the package's query/reporting layer rather than hand-rolling SQL.

Where to look first

• config/glimpse.php — enable/disable switch, retention, and any tracking filters. This is the file you will touch most.
• database/migrations/*glimpse* — tells you exactly which columns and indexes you can query and aggregate on.
• src/Console/ — the scheduler commands that v0.5.1 fixed the autoregistration for; read their signatures to understand what runs and when.
• Middleware / service provider — determines how views get recorded (request middleware vs. explicit calls), which drives your whole implementation pattern.

Implementation Patterns

Tracking

• Middleware (default path). Register the package middleware on the web group so every front-end request is captured automatically. Scope it deliberately: apply it to your public route group, not globally, so you don't pollute analytics with /admin, /nova, /horizon, health checks, or asset routes.
• Explicit recording. For SPAs, Livewire, or non-GET flows where middleware can't see the "page view" as a distinct navigation, call the package's recording API from the controller/component. This is also the cleaner option when you need to attach user or tenant context.
• Exclusions in config, not in code. Keep bot/crawler filtering, ignored paths, and authenticated-user rules in config/glimpse.php. Filtering at the config layer survives route refactors; if statements sprinkled through middleware don't.

Reading the data

• Build your own dashboard queries on top of glimpse_page_views for anything the package doesn't ship. Typical shapes: views per path per day, unique visitors per period, top referrers, entry pages.
• Add your own covering index only after checking the published ones — v0.5.1 touched index definitions, so re-read the migration before adding a composite index that may now be redundant.
• For anything heavier than ad-hoc reporting, aggregate nightly into a summary table rather than scanning glimpse_page_views on every dashboard load.

Scheduling

• Do not register the package commands yourself. v0.5.1 fixed missing autoregistration; the commands now come with the package. Adding your own $schedule->command('glimpse:...') entry creates duplicate executions — usually harmless, occasionally not (double pruning is fine, double aggregation is not).
• Make sure the scheduler actually runs in every environment you expect analytics in: * * * * * php artisan schedule:run in cron, or php artisan schedule:work locally/in containers.
• After upgrading, run php artisan schedule:list and diff against what you previously registered manually, then delete your old entries.

Testing

• Disable tracking in phpunit.xml via the config flag, or the middleware will write rows during every feature test and slow the suite.
• Use RefreshDatabase and assert against glimpse_page_views directly for the small number of tests that cover tracking behaviour. Keep it to a couple of tests — don't couple your suite to the package's internal schema more than necessary.

Gotchas and Tips

Upgrading from v0.5.0 — the migration fixes

• The index-name typo and the index-length fix both live in migration files. If you published migrations under v0.5.0 and already ran them, republishing will not retroactively fix your database — the old migration is recorded in the migrations table and won't re-run. Write a small corrective migration that drops the old index by its misspelled name and adds the corrected one, or re-publish and hand-edit if you haven't shipped to production yet.
• Never edit an already-applied migration in a deployed environment. The down() path will reference an index name that no longer matches reality, so migrate:rollback will fail with "can't drop index" errors. Drop by the old name explicitly in your corrective migration.
• Index length constraint is the classic MySQL/MariaDB problem: utf8mb4 costs 4 bytes per character, and older InnoDB builds cap index keys at 767 bytes, so an indexed VARCHAR(255) URL column blows up at migrate time. v0.5.1 fixes the definition, but it's worth checking your own added indexes on that table against the same limit — if you're on MySQL < 5.7.7 or MariaDB < 10.2.2, shorten the column or index a prefix. Setting Schema::defaultStringLength(191) in AppServiceProvider is the blunt instrument if you hit this elsewhere.
• If the original migration failed halfway, you may have a partially-created table. Drop glimpse_page_views and re-run rather than trying to patch it incrementally.

Scheduler

• Symptom of the pre-0.5.1 bug: analytics data accumulates but never gets pruned or aggregated, and schedule:list is empty of glimpse entries. After upgrading, confirm the entries appear. If they still don't, you likely have a cached config or a cached schedule: run php artisan config:clear and php artisan optimize:clear.
• In multi-server setups, add ->onOneServer() semantics yourself if the package commands aren't already guarded — duplicate aggregation across nodes is the failure mode to watch for.

Config and debugging

• Always php artisan config:clear (or optimize:clear) after touching config/glimpse.php. Cached config silently ignores your changes and is the number-one cause of "tracking isn't working."
• If rows aren't appearing: check the enabled flag, then whether the middleware is actually in the resolved middleware stack (php artisan route:list -v on a target route), then whether your exclusion rules are matching more broadly than intended.
• Retention/pruning is destructive. Set the retention window conservatively on first deploy and confirm the pruning command's cutoff semantics before letting it run on real data.
• Extension points to prefer: config-driven filters and the package's recording API. Avoid subclassing internals or reaching into the service container for package classes — this package is pre-1.0 and has shipped three schema-level fixes in a single patch release, so internal structure is still moving. Keep your integration at the config + public API boundary and upgrades will stay boring.

Version pinning

• Given the cadence of schema fixes, pin to ^0.5.1 rather than ^0.5 and read the release notes for each 0.5.x. A patch-level migration change is unusual, and any future schema change will require the same corrective-migration dance described above.