Lara Lens Laravel Package

Getting Started

LaraLens is a diagnostics/insight package for Laravel apps — install it into the app you actually want to observe, not into a shared package skeleton.

1. composer require hi-folks/lara-lens (dev dependency if you only want local insight).
2. Check auto-discovery picked up the service provider, then publish the config: php artisan vendor:publish --tag=lara-lens-config (tag name may differ — check php artisan vendor:publish output).
3. Open config/lara-lens.php first. This is where you decide what is inspected, which route/dashboard is registered, and which middleware protects it. Nothing else in the package matters until that file reflects your environment.
4. First use case: run the package's artisan entry point (typically php artisan lara-lens or similar — confirm via php artisan list | grep lens) against a local app and read the output as a pre-deploy sanity check: PHP/Laravel versions, DB connectivity, cache/queue drivers, storage permissions.

If the dashboard route is enabled, hit it once locally and once on staging before you trust it. Treat the first run as a smoke test of your environment, not of the package.

Implementation Patterns

Environment-gated dashboard. Register the route only outside production, or wrap it in your existing auth + a gate. The common pattern is ->middleware(['web', 'auth', 'can:viewLaraLens']) in the config, with the can ability defined in AuthServiceProvider. Do not rely on the package's default middleware.

Scheduled snapshot for trends. If the package exposes a command that emits a report, schedule it in routes/console.php (Laravel 11+) at low frequency — hourly at most, daily is usually enough — and persist the output to a log channel or a small table. That turns a one-off inspection into something you can diff after a deploy.

Pre-deploy checklist hook. Wire the command into CI as a non-blocking step (|| true) first. Once the checks are stable for your stack, make it blocking. This is where the package earns its place day-to-day: catching a missing storage symlink or wrong queue driver before it becomes a 2am page.

Local debugging companion. It complements Telescope, not replaces it. Telescope answers "what happened in this request"; LaraLens answers "is this environment wired correctly". Keep Telescope for request-level traces and use LaraLens for configuration/environment state.

Custom checks. Most insight packages expose an extension point (a check/collector interface or a config array of callables). Register app-specific checks there — e.g. "S3 bucket reachable", "Horizon supervisor running" — so your team's invariants live next to the package's generic ones instead of in a separate script.

Facade/service calls in tests. If a facade is available, assert the expected shape in a feature test rather than snapshotting the whole payload — the payload will drift between minor releases.

Gotchas and Tips

• PHP 8.4 alignment in v1.0.1. This release is a PHP 8.4 compatibility bump. Check composer.json constraints before upgrading; if the package now requires ^8.4, your CI matrix and any platform.php config in composer.json must match or composer update will silently resolve to the older v1.0.0.
• Config caching. Any config change requires php artisan config:clear in local/dev. A stale cached config is the most common reason the dashboard shows values that don't match .env.
• Exposed routes. The dashboard route is registered by the package. Verify with php artisan route:list | grep lens that it is not publicly reachable in production. Add the gate even if you think the route is disabled — config toggles get flipped.
• Expensive checks. Disk, DB, and external-service checks can be slow. If the package runs them per-request on the dashboard, enable any built-in cache/TTL option rather than calling the dashboard in a loop.
• Debugging wrong values. Most "the package reports the wrong driver" issues are resolved by php artisan about — compare outputs. If about agrees with the package, the problem is your config, not the package.
• Version pinning. This is a 1.0.x line with a single maintainer. Pin to ^1.0 and read the changelog on each patch; the changelog here is a one-line PHP bump, which is a good sign, but patch releases in diagnostics packages can still change output formats.
• Extension points over forks. If a check is missing, prefer the package's registration hook or a small custom artisan command. Forking a single-maintainer diagnostics package means you own PHP-version bumps yourself — exactly the kind of maintenance this release just did for you.