Laravel Google Lighthouse Laravel Package

Getting Started

The package is a thin wrapper around the Google Lighthouse CLI, so the first thing to understand is that you are not installing a PHP-native auditor — you are shelling out to Node/Chrome. Treat setup as two layers: the Composer install, and the runtime prerequisites.

Minimal steps:

1. Composer install and pin. The package is archived and its last release (1.2.0, Aug 2023) targets Laravel 9/10 only. Add it with an explicit constraint rather than ^ floating if your lockfile discipline matters, and confirm the resolved version in composer.lock.
2. Publish the config. Laravel-native config is advertised, so run the vendor publish for the package's config and read it before writing any audit code. This file is where Chrome flags, Lighthouse CLI options, categories, and score thresholds live — it doubles as your quickest map of the package's surface area.
3. Verify the external toolchain. Lighthouse needs a Chrome/Chromium binary reachable from the process. Confirm chrome/chromium exists on the host and set the path in config. In containers you almost always need --no-sandbox and a larger /dev/shm, so check the config exposes Chromium flags. If this step is wrong you get opaque failures, not helpful exceptions.
4. Run one audit in the foreground. Use the Artisan command against a known-good URL (e.g. your own homepage or https://example.com) and confirm you get four scores back: performance, accessibility, best practices, SEO. Doing this in php artisan tinker or via the fluent API is the fastest way to learn the actual builder signatures, since the README is thin and the package is unmaintained.

Where to look first: the published config file, then the service provider registration (to confirm what's bound in the container and what facade alias is available). Only then read the fluent API.

First real use case: audit a single staging URL and read the four category scores plus the raw JSON report. That single audit tells you everything about whether the package fits — runtime viability of Chrome, audit duration, and report structure — before you write a single job or threshold check.

Implementation Patterns

Fluent audits inside queued jobs. Audits are slow (seconds to tens of seconds per URL) and resource-hungry (a real Chrome instance). Never run them inline in a web request. Wrap the fluent builder in a queued job, one URL per job, and keep the job timeout generous and the queue worker isolated from your interactive workloads. This is the pattern that matters most: the package gives you the audit, not the orchestration.

Artisan command as a scheduled task. The bundled command is the cheapest integration point — schedule it in Kernel::schedule() (or the console routes file on newer setups) to audit a fixed set of URLs nightly. For a small site, this is genuinely all you need: nightly audit, results persisted, one dashboard.

Threshold gates for CI/monitoring. The advertised "score thresholds" feature is best used as a pass/fail primitive. Set per-category minimums in config, run the audit, and fail the job (or emit a notification) when a score regresses. Keep thresholds in config, not hard-coded, so a performance budget can be tuned without a deploy. Pair this with a snapshot of the previous score so you're alerted on regression, not just on absolute failure — absolute budgets drift and get noisy.

Persist the raw JSON, not just the scores. Store the full report blob alongside the four headline scores (a JSON/longText column plus indexed score columns works well). Scores alone are useless when a number drops and you need to know which audit failed. This also lets you re-derive metrics later without re-running an expensive audit — important with an archived, unmaintained package you may replace.

Multi-URL orchestration via fan-out. For more than a handful of URLs, dispatch one job per URL from a parent job or command, then aggregate. Don't loop inside a single job — one Chrome crash shouldn't discard the whole batch, and per-URL jobs give you natural retry isolation.

Config over code for categories and Chrome flags. The package exposes categories and Lighthouse/Chrome options through config. Drive variant audits (mobile vs desktop, reduced category set) from config profiles rather than branching in code — it keeps the call sites identical and makes the "what did we change?" diff obvious in review.

Gotchas and Tips

• Archived and unpinned in time. Last release was August 2023, targeting Laravel 9/10. There is no Laravel 11/12 support and will not be one. Pin the version, and treat any future framework upgrade as a forced fork-or-replace decision. Budget for that now: keep your integration behind your own small service/facade so swapping the package for a hand-rolled CLI wrapper is a one-class change.
• "Thin wrapper" is the honest framing. The value is the Laravel glue (config, command, fluent API), not the auditing. If you hit friction, replacing it with a few dozen lines around proc_open on the Lighthouse CLI is a realistic exit — which is also the best argument for isolating it.
• Chrome is the real dependency, not Composer. Most "the package is broken" failures are environmental: no Chromium, wrong path, missing --no-sandbox in Docker, or /dev/shm too small causing silent Chrome crashes. Reproduce audits manually at the CLI level before blaming the PHP layer.
• Version skew with Lighthouse itself. The package wraps whatever Lighthouse CLI is on the machine. If Node/Lighthouse versions differ between your laptop, CI, and production, scores and report shapes will drift. Pin the Lighthouse version in your image and treat it as part of the application's dependency graph.
• Audit duration and timeouts. Expect multi-second-to-minute runs, worse on cold caches. Set timeout above your worst observed run, and remember queue retries will happily launch another Chrome — cap tries and use backoff so a flaky target doesn't spawn a Chrome stampede.
• Resource contention in CI. Parallel audits on a shared runner will fight for memory and produce false regressions. Serialize performance audits in CI, or give them a dedicated runner. Accessibility/SEO audits are more forgiving than performance ones.
• Report payload size. Raw JSON reports can be large (hundreds of KB each). Storing them per-URL per-night adds up quickly; plan retention (e.g. keep the latest N, or drop raw JSON after extracting metrics) before this becomes a database surprise.
• Debugging failures. When an audit throws, you usually get a CLI error surfaced through the wrapper with little context. Log the full command and raw stdout/stderr in the job, not just the exception message — with an unmaintained package and no upstream issue triage, your own logs are the only diagnostic you'll have.
• Extension points are your safety net. Because the package is archived, drive behavior through its config (categories, Chrome options, thresholds) and keep custom logic in your job/service layer. Avoid subclassing or monkey-patching package internals — there is no maintainer to align with, so anything you override is permanently yours.