Symfony Metrics Laravel Package

Getting Started

• Bump the dependency first. The new feature requires quiet-metrics/php-metrics: ^0.6; run composer require quiet-metrics/php-metrics:^0.6 and check composer why quiet-metrics/php-metrics in case another package pins it lower. At 0.x, treat minor bumps as potentially breaking and read the changelog before deploying.
• Two config keys drive the feature: secret_key (must be non-empty) and the new seo_crawl boolean (default false). Put both in .env / .env.example:

  QUIET_METRICS_SECRET_KEY=...
  QUIET_METRICS_SEO_CRAWL=false
  

  The docs' '%env(bool:QUIET_METRICS_SEO_CRAWL)%' form is Symfony placeholder syntax — in a Laravel config file you want env('QUIET_METRICS_SEO_CRAWL', false) cast to bool.
• First use case: enable it in staging (QUIET_METRICS_SEO_CRAWL=true), then verify the endpoint manually before touching production:

  curl -i https://staging.example.com/.well-known/quietmetrics.json
  curl -I https://staging.example.com/.well-known/quietmetrics.json
  

  Confirm 200, Content-Type: application/json, Cache-Control: no-store, and that the body is the ownership proof. Only then flip it on in production and hit "verify" in the Quiet Metrics SEO tab.
• Where to look first: the newly registered SiteVerificationListener (priority 200 on kernel.request) and the config node backing seo_crawl. Also grep your codebase, public/, and your web server config for anything else claiming /.well-known/ — a collision is the most likely reason verification silently fails.

Implementation Patterns

• Environment matrix, not a single flag. Keep seo_crawl=false in .env.example and local/CI, true only in staging and production. Since the listener is registered unconditionally and decides per request, one codebase can serve all environments.
• Verify-from-the-outside loop. Add the two curl calls (GET + HEAD) to your deploy smoke-test script or a Pest/PHPUnit feature test that asserts status, content type, no-store, and that the response body does not contain secret_key.
• Uptime monitoring with HEAD. A HEAD check on the well-known path is cheap, exercises the same code path, and catches a regression where a new catch-all route or middleware starts swallowing /.well-known/*.
• Precedence check in CI. Run php artisan route:list --path=.well-known after adding routes or a new front-controller/rewrite rule. Any route or static file matching that path will shadow or be shadowed by the verification endpoint.
• Treat the secret as deploy-time state. Generate a dedicated secret per environment; rotate by deploying the new value and re-running verification in the SEO tab in the same change window. Keep it out of config:cache artefacts you might commit or share.
• Middleware bridging (Laravel). The release describes a Symfony kernel.request subscriber; Laravel has no such event. If the package doesn't ship a Laravel service provider for this, implement the equivalent as a global middleware that short-circuits the path and returns the same JSON/HEAD/no-store response, registered early (before session/auth) and skipped for sub-requests.
• Extension points. If you need different behaviour (extra headers, logging, a different proof format), decorate/replace the listener rather than editing vendor code. Serving the JSON as a static file is the zero-code alternative, but you lose the runtime env toggle and the no-store guarantee.

Gotchas and Tips

• seo_crawl: true alone does nothing. The endpoint is only served when secret_key is also set. If verification 404s, check the secret before debugging the flag.
• The listener is always registered. That's deliberate (the %env()% value is only known at runtime), but it means a per-request path comparison on every request even when the feature is off. Keep it cheap, and don't add expensive work to that listener or to middleware ordered alongside it.
• Priority 200 means it runs before the session, router, and firewall. Good for latency and for not requiring auth, but it also means your maintenance-mode page, IP allowlist, or WAF rules may intercept the request before the listener ever sees it. Test from an external network, not just from your machine.
• Main request only. Sub-requests (ESI/fragments, internal forwards, HttpKernel::SUB_REQUEST) won't get the proof. Feature tests that build a request manually may not mark it as a main request — assert via a real HTTP call if the test fails unexpectedly.
• Dotfile rules eat .well-known. Nginx location ~ /\. deny blocks, Apache FilesMatch rules, and some CDNs block or rewrite dot-prefixed paths. Add an explicit allow for /.well-known/ before blaming the package.
• Static file shadowing cuts both ways. A leftover public/.well-known/quietmetrics.json (or a reverse-proxy try_files) will take precedence over the app and won't carry Cache-Control: no-store. Delete stale copies after enabling the dynamic endpoint.
• no-store is only as good as your edge. CDNs and corporate proxies sometimes cache anyway. Purge the path after rotating the secret or changing the flag, or verification may serve a stale proof.
• Don't log the response. Whatever the proof derivation is, avoid dumping the well-known response body into request logs or an APM trace where the secret could be reconstructed; also confirm the payload doesn't echo secret_key verbatim.
• Config caching will bite you. env() called outside config files returns null once config:cache has run. Read the flag through a config key, and remember that changing the env value may require a config cache clear (or a restart) depending on how the bundle resolves it — verify by toggling and re-curling rather than assuming.
• Boolean coercion. env('QUIET_METRICS_SEO_CRAWL') returns the string "false", which is truthy. Always cast: (bool) env(..., false) or Laravel's env() with an explicit boolean default and an in_array-style normaliser.
• Pin and review. ^0.6 on a 0.x package allows breaking changes in 0.7. Pin exactly in composer.lock, and re-run the GET/HEAD smoke test after every dependency bump.