README

Automatically detect and report broken links, missing images, and invalid embeds in your Craft CMS content.

Features

🔍 Automatic Scanning - Scans entries for broken links, missing assets, and invalid embeds
📊 Dashboard UI - View all broken links with filtering and sorting
⚠️ Entry Alerts - Warnings displayed directly in the entry editor
🎯 Field Type Support - Redactor, CKEditor, Matrix, Table, Assets, Plain Text, Super Table
🔄 Background Processing - Uses Craft's queue system for non-blocking scans
🖥️ CLI Commands - Scan from the command line
🎛️ Flexible Settings - Control what to scan, when, and how
🔐 Permission Controls - Granular permissions for viewing and triggering scans

Requirements

Craft CMS 5.0+
PHP 8.2+

Installation

Add the plugin to your project:

composer require yourcompany/craft-broken-link-checker

Install the plugin:

php craft plugin/install broken-link-checker

Usage

Dashboard

Navigate to Broken Link Checker in the control panel to:

View all broken links
Filter by section, site, or error type
Export results as CSV
Trigger manual scans

Entry Editing

When editing an entry with broken links, you'll see a warning banner with:

List of broken links in that entry
Quick rescan button
Link to view all issues

CLI Commands

Scan all entries:

php craft broken-link-checker/scan/run

Scan specific entry:

php craft broken-link-checker/scan/run --entryId=123 --siteId=1

Run scan synchronously (wait for completion):

php craft broken-link-checker/scan/run --sync

View statistics:

php craft broken-link-checker/scan/stats

Clear all records:

php craft broken-link-checker/scan/clear

Permissions

Grant these permissions to user groups as needed:

View broken links dashboard - View the broken links dashboard
Trigger link scans - Manually trigger scans
Manage plugin settings - Access plugin settings

Configuration

Settings

Access settings via Settings → Broken Link Checker or by clicking the gear icon in the plugin section.

Scanning Options:

Choose which sections and sites to scan
Select field types to include
Set scan frequency (manual, hourly, daily, weekly)
Enable scan on entry save

External URL Options:

Set timeout duration
Configure redirect following
Set max redirect depth
Limit concurrent requests

Advanced:

Set batch size for queue processing
Define URL patterns to ignore (wildcards or regex)

Example: Ignore Patterns

https://localhost/*
https://example.com/admin/*
/^https:\/\/.*\.local\//

Error Types

The plugin detects and categorizes these error types:

404 - Page not found
500 - Server error
Timeout - Request timed out
Missing Asset - Asset deleted or file missing
Invalid Internal Link - Internal link points to non-existent entry
Redirect Loop - Too many redirects
SSL Error - Certificate issue
DNS Error - Domain not resolved

Performance Considerations

All scans run in the background via Craft's queue system
External URL checks respect timeouts and rate limits
Batch size can be adjusted for your server capacity
Consider running scheduled scans during off-peak hours

Troubleshooting

Scans not running automatically:

Check that Craft's queue is processing (run php craft queue/run)
Verify scan frequency is not set to "Manual Only"

False positives for external links:

Some sites block automated requests - add them to ignore patterns
Increase timeout if sites are slow to respond
Check if sites require specific user agents

High memory usage:

Reduce batch size in settings
Limit concurrent external requests
Process fewer field types

Support

For issues, feature requests, or questions:

GitHub Issues: [your-repo-url]
Documentation: [your-docs-url]

License

MIT

burnthebook / craft-broken-link-checker

Maintainers

Details