Global Ray Laravel Package

Technical Evaluation

Architecture Fit

• Debugging Tooling: Fits seamlessly into PHP/Laravel ecosystems where real-time debugging (e.g., dump(), log()) is critical. Complements existing tools like Laravel Debugbar or Tideways.
• Global Scope: Unlike framework-specific packages, this enables debugging across all PHP files, including CLI scripts, non-Laravel apps, or legacy codebases.
• Ray Integration: Leverages Spatie’s Ray app for a unified debugging experience (PHP + JS/TS), reducing context-switching for devs.

Integration Feasibility

• Low Friction: Single-composer install (spatie/global-ray) with zero config for basic usage. Ray’s desktop app must be installed separately.
• Laravel-Specific: Works out-of-the-box with Laravel’s dump()/dd() but requires explicit ray() calls for custom output.
• Non-Laravel PHP: Ideal for debugging standalone scripts or microservices where traditional logging is insufficient.

Technical Risk

• Ray Dependency: Requires Ray’s desktop app (proprietary, paid beyond trial). Downtime if Ray’s MCP server (for AI/remote debugging) is unavailable.
• Performance Overhead: Minimal for debug-only use, but global instrumentation could impact production if misconfigured (e.g., enabled in app()).
• Compatibility: Tested on PHP 8.1+, but edge cases may exist with older versions or non-standard PHP setups (e.g., custom autoload).
• Security: Debug output may expose sensitive data if not filtered (e.g., passwords in ray() calls).

Key Questions

1. Debugging Scope: Should Ray be enabled globally (all PHP files) or scoped to specific environments (e.g., local only)?
2. Data Sensitivity: How will PII/secret masking be handled in debug output? (Ray supports redaction but requires explicit configuration.)
3. Ray Licensing: Will the team adopt Ray’s paid license for full features (e.g., performance profiling, AI integration)?
4. Alternatives: Compare with existing tools (e.g., Laravel Debugbar, Xdebug, Tideways) for feature parity and cost.
5. CI/CD Impact: Will Ray output clutter CI logs? Need to exclude CI environments via config.
6. Performance Baseline: Measure overhead in production-like loads (e.g., high-traffic APIs) with Ray enabled.

Integration Approach

Stack Fit

• PHP/Laravel: Native support for dump()/dd(); minimal changes needed. For non-Laravel PHP, requires explicit ray() calls.
• Monorepos: Useful for debugging across multiple PHP projects (e.g., Laravel + Symfony) from a single Ray instance.
• Hybrid Stacks: Bridges PHP and JavaScript debugging (Ray supports both), useful for full-stack teams.

Migration Path

1. Trial Phase:
   • Install globally: composer global require spatie/global-ray.
   • Test in a non-production environment (e.g., php artisan tinker or CLI scripts).
   • Verify Ray’s desktop app connects and displays expected output.
2. Configuration:
   • Add to composer.json (if project-specific): "spatie/global-ray": "^1.0".
   • Configure environment-specific enablement (e.g., .env):

     RAY_ENABLED=true
     RAY_MCP_SERVER=https://mcp.myray.app  # For AI features
     

   • Exclude sensitive data via Ray’s redaction rules.
3. Laravel-Specific:
   • Replace dd() with ray()->dd() for custom formatting (e.g., HTML tables).
   • Override AppServiceProvider to auto-wrap dump():

     if (app()->environment('local')) {
         \Spatie\GlobalRay\Ray::enable();
     }
     

4. CI/CD:
   • Disable Ray in CI (e.g., RAY_ENABLED=false in .env.ci).
   • Add a pre-commit hook to scan for accidental ray() calls with sensitive data.

Compatibility

• PHP Versions: Tested on 8.1+; may need polyfills for older versions.
• Ray App: Requires Ray desktop app (Mac/Windows/Linux). Docker/Kubernetes setups need host access to Ray’s socket.
• Existing Debugging Tools: Can coexist with Xdebug but may require port conflicts (Ray uses port 8000 by default).
• Legacy Code: Works with procedural PHP but lacks IDE integration for static analysis.

Sequencing

1. Phase 1: Enable in development for core team members (1–2 weeks).
2. Phase 2: Roll out to wider dev team with documentation on best practices (e.g., avoiding ray() in loops).
3. Phase 3: Evaluate Ray’s paid features (e.g., performance profiling) and integrate MCP server for AI-assisted debugging.
4. Phase 4: (Optional) Build custom Ray handlers for framework-specific data (e.g., Eloquent queries).

Operational Impact

Maintenance

• Package Updates: Low-maintenance (MIT-licensed, active Spatie support). Monitor for breaking changes in Ray’s MCP server.
• Configuration Drift: Risk of enabling Ray in production if not gated by environment checks. Mitigate with:
  • .env guards: RAY_ENABLED=app()->environment('local').
  • CI checks: Fail builds if RAY_ENABLED=true in non-local environments.
• Dependency Bloat: Global install adds ~1MB to composer global. Project-specific installs avoid this.

Support

• Onboarding: Steep learning curve for teams unfamiliar with Ray’s UI. Requires:
  • 30-minute workshop on Ray’s features (e.g., pausing execution, performance tabs).
  • Cheat sheet for common commands (ray()->table(), ray()->pause()).
• Troubleshooting:
  • Connection Issues: Ray app not launching? Check firewall/socket permissions.
  • Missing Output: Verify RAY_ENABLED=true and Ray’s desktop app is running.
  • Performance: High-volume ray() calls may lag UI; use batching or sampling.
• Escalation Path: Spatie’s GitHub issues for package bugs; Ray’s support for app issues.

Scaling

• Debug Output Volume: Ray’s free tier limits 20 messages/session. Paid license required for:
  • High-frequency debugging (e.g., real-time APIs).
  • Long-running processes (e.g., queues, CLI jobs).
• Team Scaling: Ray’s collaborative features (shared sessions) enable pair debugging but require license coordination.
• Infrastructure: No server-side scaling needed; all processing happens locally.

Failure Modes

Ramp-Up

• Developer Adoption:
  • Pros: Real-time debugging reduces context-switching; unified PHP/JS tooling.
  • Cons: Requires cultural shift from dd() to Ray’s UI. Resist with:
    • Incentivize Ray usage in PR reviews (e.g., "Include a Ray screenshot").
    • Showcase success stories (e.g., "Ray helped debug this race condition in 5 mins").
• Training:
  • Async: Recorded demo of Ray’s key features (e.g., Spatie’s Ray tutorial).
  • Sync: Brown-bag session on advanced features (e.g., ray()->pause()).
• Documentation:
  • Internal wiki with:
    • Quick-start guide (install + first ray() call).
    • Anti-patterns (e.g., "Don’t use ray() in production").
    • Screenshots of common workflows (e.g., debugging a failed queue job).