X Ray Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/x-ray
   

   Add the service provider to config/app.php:

   Spatie\XRay\XRayServiceProvider::class,
   

2. First Scan: Use the scan() method to detect Ray calls in your project:

   use Spatie\XRay\Facades\XRay;
   
   $results = XRay::scan(base_path());
   

   Outputs a structured array of found Ray calls with file paths, line numbers, and context.

3. Quick Use Case: Run a one-off scan during debugging to locate all Ray logging calls in a specific directory:

   php artisan xray:scan app/Http/Controllers
   

Implementation Patterns

Common Workflows

1. Integrating with CI/CD: Add a GitHub Action or GitLab CI step to scan for Ray calls before merging:

   # .github/workflows/xray.yml
   - name: Scan for Ray calls
     run: php artisan xray:scan app --format=json > ray_calls.json
   

2. Pre-Commit Hooks: Use husky or pre-commit to block commits with new Ray calls:

   composer require --dev spatie/x-ray
   

   Add to .husky/pre-commit:

   php artisan xray:scan --fail-on-new
   

3. Dynamic Scanning in Tests: Verify Ray calls are removed after refactoring:

   public function test_ray_calls_removed()
   {
       $results = XRay::scan(base_path('app'));
       $this->assertEmpty($results, 'Ray calls found in app directory');
   }
   

Integration Tips

• Customize Output: Format results as JSON, CSV, or markdown for team reviews:

  XRay::scan(base_path())->toJson()->save('ray_calls.json');
  

• Exclude Directories: Ignore vendor/ or tests/ in scans:

  XRay::scan(base_path())->ignoreDirectories(['vendor', 'tests']);
  

• Laravel Artisan Command: Use the built-in command for CLI workflows:

  php artisan xray:scan --path=app/Http --format=table
  

Gotchas and Tips

Pitfalls

1. False Positives:

   • The scanner may flag Ray:: as a call even in comments or strings.
   • Fix: Use --strict to avoid partial matches or whitelist files:

     XRay::scan(base_path())->whitelist(['app/Helpers/ray-helpers.php']);
     

2. Performance:

   • Scanning large codebases (e.g., monorepos) can be slow.
   • Tip: Cache results or scan incrementally:

     XRay::scan(base_path())->cacheFor(minutes: 60);
     

3. Edge Cases:

   • Dynamic class names (e.g., ${class}::ray()) won’t be detected.
   • Workaround: Use --regex to customize patterns:

     XRay::scan(base_path())->useRegex('/\bRay::\w+/');
     

Debugging

• Verbose Mode: Enable debug output for scanner internals:

  php artisan xray:scan --verbose
  

• Dry Run: Test configurations without modifying files:

  php artisan xray:scan --dry-run
  

Extension Points

1. Custom Call Handlers: Extend the scanner to detect other logging systems (e.g., Log::):

   XRay::extend(function (Scanner $scanner) {
       $scanner->addPattern('/Log::\w+/');
   });
   

2. Post-Scan Actions: Hook into the scanned event to automate fixes:

   XRay::scanned(function (array $results) {
       foreach ($results as $result) {
           // Replace Ray calls with Log:: here
       }
   });
   

3. Configurable Ignores: Override default ignores in config/xray.php:

   'ignored_directories' => [
       'vendor',
       'node_modules',
       'storage/logs',
   ],