Laravel Link Checker Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-link-checker
   

   Publish the config file:

   php artisan vendor:publish --provider="Spatie\LinkChecker\LinkCheckerServiceProvider"
   

2. First Run: Execute the command to check all links in your app:

   php artisan link-checker:check
   

   • By default, it checks routes/web.php and routes/api.php for HTTP links.
   • Results are logged to storage/logs/laravel-link-checker.log.

3. Quick Use Case:

   • Run a one-time check before a deployment to catch broken links.
   • Schedule it via Laravel’s task scheduler (e.g., * * * * * php artisan link-checker:check --quiet) to run nightly.

Where to Look First

• Config File: config/link-checker.php – Customize ignored URLs, status codes, and email notifications.
• Command: php artisan link-checker:check – Core command with flags like --ignore-ssl, --quiet, and --email.
• Service Provider: Spatie\LinkChecker\LinkCheckerServiceProvider – Registers the command and config.

Implementation Patterns

Workflows

1. Integrate with CI/CD:

   • Add the command to your phpunit.xml or GitHub Actions workflow to fail builds on broken links:

     <php>
         <env name="LINK_CHECKER_FAIL_ON_BROKEN" value="true"/>
     </php>
     

   • Example GitHub Actions step:

     - name: Check Links
       run: php artisan link-checker:check --fail-on-broken
     

2. Custom Link Sources:

   • Extend the LinkChecker class to scan additional files (e.g., Markdown, Blade templates):

     use Spatie\LinkChecker\LinkChecker;
     
     $checker = new LinkChecker();
     $checker->addFileToCheck('/path/to/custom/file.md');
     $checker->check();
     

3. Email Notifications:

   • Configure link_checker.email in config/link-checker.php to send reports to stakeholders:

     'email' => [
         'to' => 'team@example.com',
         'from' => 'monitor@example.com',
         'subject' => 'Broken Links Report',
     ],
     

   • Trigger via command:

     php artisan link-checker:check --email
     

4. Scheduled Checks:

   • Add to app/Console/Kernel.php:

     protected function schedule(Schedule $schedule)
     {
         $schedule->command('link-checker:check --quiet')
                  ->dailyAt('3:00');
     }
     

Integration Tips

• Exclude URLs: Use the ignore_urls config array to skip internal routes or external services:

  'ignore_urls' => [
      'https://example.com/api/*',
      'mailto:*',
      'tel:*',
  ],
  

• Custom Status Codes: Override default 200-300 range in config:

  'allowed_status_codes' => [200, 301, 302, 404],
  

• Parallel Checks: For large apps, leverage Laravel’s queue system to process links in batches:

  $checker->checkInParallel(5); // Process 5 links concurrently
  

• Blade Template Links: Ensure Blade directives like @url() or @route() resolve to absolute URLs before checking.

Gotchas and Tips

Pitfalls

1. SSL Warnings:

   • Ignore SSL errors with --ignore-ssl, but be cautious in production (may hide real issues).
   • For development, use --ignore-ssl temporarily:

     php artisan link-checker:check --ignore-ssl
     

2. Dynamic Routes:

   • Links generated via JavaScript (e.g., window.location.href) won’t be caught. Use static analysis or frontend tools (e.g., Puppeteer) for these.

3. Rate Limiting:

   • Aggressive checks may trigger rate limits on external APIs. Add delays:

     'delay_between_checks' => 1000, // Milliseconds
     

4. False Positives:

   • Redirects (301/302) may appear broken if not configured in allowed_status_codes.
   • Test with --verbose to debug:

     php artisan link-checker:check --verbose
     

Debugging

• Log Inspection: Check storage/logs/laravel-link-checker.log for detailed errors (e.g., timeouts, SSL issues).

• Dry Run: Use --dry-run to preview links without making requests:

  php artisan link-checker:check --dry-run
  

• Timeouts: Increase timeout for slow external services:

  'timeout' => 30, // Seconds
  

Extension Points

1. Custom Checkers: Extend Spatie\LinkChecker\Checkers\Checker to validate links against custom rules (e.g., API response schemas):

   namespace App\LinkCheckers;
   
   use Spatie\LinkChecker\Checkers\Checker;
   
   class ApiResponseChecker extends Checker
   {
       public function check($url)
       {
           $response = $this->httpClient->get($url);
           return $response->json('status') === 'success';
       }
   }
   

2. Database Storage: Save results to a table for historical tracking:

   use Spatie\LinkChecker\Models\Link;
   
   $links = Link::all()->where('is_broken', true);
   

3. Slack/Teams Notifications: Hook into the link-checker.after-check event to send alerts:

   // In EventServiceProvider
   protected $listen = [
       'Spatie\LinkChecker\Events\AfterCheck' => [
           \App\Listeners\SendSlackAlert::class,
       ],
   ];
   

Config Quirks

• Environment-Specific Settings: Override config in .env:

  LINK_CHECKER_IGNORE_URLS=*.staging.example.com/*
  LINK_CHECKER_TIMEOUT=15
  

• Case Sensitivity: ignore_urls patterns are case-sensitive. Use regex or lowercase URLs for consistency:

  'ignore_urls' => [
      '/api/.*/old-endpoint',
  ],
  

• Local Development: Exclude localhost or 127.0.0.1 in development:

  'ignore_urls' => [
      'http://localhost:*',
      'http://127.0.0.1:*',
  ],