Configuration

Publish the config file to edit it:

php artisan vendor:publish --tag=pagespeed-insights-config

Everything below lives under the pagespeed-insights config key.

Credentials

The key is required. There is no supported keyless mode — see Installation → Getting a PageSpeed Insights API key.

The three drivers differ only in where the key lives:

• config reads api_key above. Read-only: save() refuses, because the value is managed through config and env.
• database stores the key encrypted at rest in pagespeed_configurations. Requires the package migrations.
• cms stores the key encrypted through the CMS framework's Settings module, and is only available when artisanpack-ui/cms-framework is installed. See CMS framework.

ApiKeyRepository is a plain container bind rather than a singleton, so changing pagespeed-insights.driver at runtime takes effect on the next resolve.

The API request

Google publishes two hosts for the same API: the www.googleapis.com form used here (from Google's own Get Started guide) and the canonical discovery form, https://pagespeedonline.googleapis.com/pagespeedonline/v5/runPagespeed. Either works.

categories is written in the response-key spelling (lower-kebab). The client translates each entry to the API's upper-snake request enum — best-practices becomes BEST_PRACTICES — and repeats the category query parameter once per entry. Omitting the parameter entirely would return performance only, which is a silent way to lose three scores.

timeout sits well above a typical HTTP timeout because Google's own runs take 20–60 seconds and occasionally longer. Values that are not positive numbers fall back to 90.

store_raw_response is off by default: a single response runs to hundreds of kilobytes, so retaining every one grows the history table by two orders of magnitude for data the package has already parsed into its own columns. Turn it on temporarily when diagnosing a parsing problem against real responses, and see Retention for the window that expires the payloads again.

Queue

A dedicated queue is worth considering on a busy application: a single PageSpeed run blocks its worker for 20–60 seconds, so a scheduled cycle over a few dozen URLs will starve anything sharing the queue with it.

job.timeout sits above timeout so the HTTP client — which knows which URL it was testing — is the thing that gives up first.

job.tries applies to transient failures only. A missing API key is never retried, because no amount of waiting produces one. A genuine quota rejection releases the job with job.quota_delay rather than consuming a retry, so an exhausted quota postpones a run instead of failing it.

Rate limiting

Counted across every URL and every worker, because Google attributes quota to the API key rather than to the page being tested. A job over the budget is released back onto the queue, so a large cycle spreads itself out instead of failing.

The default of 30 is deliberately conservative. Google does not publish a PageSpeed Insights rate limit anywhere in its documentation, so the commonly cited figures are folklore rather than fact. Check the quota page for your own project in the Google Cloud Console before raising it.

Scheduling

test_frequency supports hourly, daily, weekly, and monthly; anything else falls back to weekly. Bear the API quota in mind: each run costs one request per form factor, so 200 URLs on both mobile and desktop is 400 requests per cycle.

With scheduling.enabled on, the package registers pagespeed:monitor and pagespeed:check-staleness hourly and pagespeed:prune daily, all guarded with withoutOverlapping(). Hourly is how often the package looks, not how often it tests — a URL only comes due once its own interval has elapsed, and hourly is itself a supported cadence, so anything less frequent would make it unreachable. Turn the flag off to call the commands from your own schedule.

scheduling.persist_hook_urls is not really optional. A URL contributed through ap.pageSpeed.registerUrls comes back as an unsaved model, which has nowhere to record last_tested_at — so it would read as due on every cycle whatever its cadence says, and its results would have no row to hang history from. The scheduler is the one place in the package that calls UrlRegistry::persistHookUrls() for you.

Sitemap discovery

The cap exists because a large site lists thousands of pages and every activated one costs quota on every cycle. Discovered URLs are stored inactive unless pagespeed:discover-sitemap is run with --activate. See Commands → pagespeed:discover-sitemap.

Alerts

Documented in full in Alerts. The keys:

HTTP routes

Documented in full in HTTP endpoints.

All five are read when the service provider boots. Replacing routes.middleware replaces it wholesale, including the auth entry: the package applies the stack you configure rather than adding a guard of its own on top of it.

routes.ability is the exception, and exists because of that wholesale replacement: it is appended to whatever middleware holds rather than substituted for it, so adding an authorization check does not mean restating web and auth and risking dropping one. Left unset — the default — the middleware stack is the whole authorization decision and an authenticated user is an authorized one. See HTTP endpoints for when to set it.

Retention

Two windows rather than one, because the two things a result row holds cost wildly different amounts to keep. A score row is a few dozen bytes and is the entire reason history exists — a year keeps a full seasonal cycle, so this year's Black Friday has last year's to be compared against. A retained raw_response is hundreds of kilobytes of data the package has already parsed into its own columns, kept only so a parsing problem can be diagnosed against a real payload; a month-old payload has either answered that question or never will. So the payload expires first and the row outlives it.

Both windows measure from created_at rather than fetched_at, because fetched_at is Google's own analysis timestamp and is null on a failed run — and retention has to be able to expire a failed row too.

Either window can be set to 0 to turn that half off. 0 for retention.days means history is never deleted, which is a reasonable choice on a small monitored set, but it is a choice rather than the default: an hourly cadence on 200 URLs across both form factors writes about 3.5 million rows a year. Anything that is not a positive whole number of days no larger than a century — a blank env var, a typo, a value so large that subtracting it from today overflows — is also read as off, because the alternative reading is a cutoff in the future, and a cutoff in the future matches the whole table.

See Commands → pagespeed:prune.

Degraded runs and the warnings column

A run either fails outright or completes. But "completed" is not the same as "complete": Lighthouse can return a payload that scored three categories out of four, or scored them all while losing a lab metric, or returned no CrUX field data at all. The parser tolerates each of those rather than failing the run — and records what it tolerated.

That record is the warnings JSON column on pagespeed_results, with these keys:

A run carrying any of those is degraded. It is still a completed run, still stored, and still charted — but it is a weaker measurement than a clean one, and the package treats it as such:

$result->hasWarnings();
$result->wasDegraded();
$result->warningList();          // a flat, human-readable list
$result->scores()->unrecognized();

Three consequences worth knowing about:

• The trend chart can look thin for a reason. A category that stopped being measured plots as a gap rather than as a zero, and the gap is exactly what the warnings column explains.
• A degraded run is skipped as an alert baseline by default (alerts.skip_degraded), so a clean run following a thin one is not reported as a recovery it never made. A regression detected on a degraded run is still reported, and the notification says the run was degraded.
• pagespeed:test prints every warning and carries them in --json, so a degraded run and a clean one never look the same in a build log.

See Troubleshooting → A run completed but the scores are partial.