Download the PHP package lbonnet/on-page-seo-bundle without Composer

OnPageSeoBundle

A Symfony bundle to crawl a site and audit on-page SEO signals: titles, meta descriptions, headings, image alt attributes, and duplicate titles/descriptions across pages.

Designed to run outside the request/response cycle — as a console command, a scheduled cron, or a CI check — so it fits both CI pipelines and periodic audits of a live site.

Requirements

• PHP >= 8.1
• Symfony 6.4, 7.x, or 8.x

Installation

If you don't use Symfony Flex, enable the bundle manually in config/bundles.php:

Configuration

Create config/packages/on_page_seo.yaml:

Usage

1. Console Command (CLI & CI)

The url argument is optional if on_page_seo.base_url is configured. The command exits with a non-zero status code when SEO issues are found, so it can be used as a CI check.

2. Asynchronous Execution (Messenger)

The bundle provides a CheckSeoMessage and its handler to offload the audit to an asynchronous worker queue:

3. Automated Monitoring (Symfony Scheduler)

If you use symfony/scheduler (Symfony 6.3+), you can schedule periodic audits in your application's ScheduleProvider:

4. Custom Notifications & Event Handling

When a crawl completes, a CrawlCompletedEvent is dispatched. You can listen to this event to send alerts (Slack, Email, Discord) or perform custom actions:

[!NOTE] If a CrawlCompletedEvent listener throws (e.g., a misconfigured notifier transport), the bundle catches and logs the error instead of letting it propagate — a broken notification integration won't discard an otherwise successful audit or prevent the JSON report from being saved.

5. Report Storage

By default, every completed audit automatically saves a detailed JSON snapshot in var/on_page_seo/:

To disable automatic file storage, set storage_dir: null in your bundle configuration.

Reports are rotated per crawled URL: only the storage_max_reports most recent (30 by default) are kept for a given start URL, so a daily scheduled audit doesn't grow the storage directory forever. Set it to 0 to keep every report.

Notes

SSRF protection

The crawler follows every link it finds on the pages it visits — including links planted by whoever controls the content being audited. If you point it at untrusted or third-party content, a malicious page could contain a link to http://169.254.169.254/... (cloud instance metadata), http://localhost:6379 (an internal service), or any other address on your private network, and the bundle would otherwise dutifully request it from the machine running the audit.

To prevent this, requests are made through Symfony's NoPrivateNetworkHttpClient, which blocks requests resolving (including via DNS) to private, loopback, or link-local IP ranges. This is on by default and applies to every HTTP request the bundle makes.

Set allow_private_network: true only if you intentionally want to audit an internal network (e.g., a staging site reachable solely from behind a VPN) — and only when the content being crawled is fully trusted, since this also re-opens the SSRF exposure described above.

Being a polite crawler

Two settings help keep an audit well-behaved:

• request_delay_ms (200 by default) enforces a minimum delay between consecutive requests to a host. The host you're auditing is unthrottled against itself by default — it's the one site you actually control and want audited quickly — so this setting only ever slows down requests to other hosts the crawl happens to reach.
• respect_robots_txt (on by default) fetches the audited site's robots.txt once and stops the crawler from following or auditing further pages under a disallowed path. It doesn't affect the URL you explicitly pass as the audit's starting point. If that same robots.txt publishes a Crawl-delay for our user agent, it overrides request_delay_ms for the audited host specifically — the site owner's explicit request takes precedence over the "unthrottled against itself" default.

Query strings and duplicate content false positives

Pages are audited as-is: /blog?p=1 and /blog?p=2 are treated as two distinct pages, since a query string often identifies genuinely different content rather than noise. On sites where some parameters are pure noise instead (pagination, sorting, tracking like utm_*), this can trigger duplicate-title/duplicate-description false positives between what is really the same page under different query strings — use exclude_patterns to filter those out explicitly, e.g. '#[?&]utm_#' or '#\?page=#'.

Security

To report a vulnerability, please don't open a public issue — see SECURITY.md for how to report it privately.

License

MIT — see LICENSE.