Craft Ray Laravel Package

Technical Evaluation

Architecture Fit

• Debugging Layer Integration: spatie/craft-ray integrates seamlessly with CraftCMS’s debugging ecosystem, leveraging Ray’s cross-language debugging capabilities. It acts as a middleware layer between Craft’s native logging (craft\helpers\Console) and Ray’s desktop UI, making it ideal for teams already using Ray for Laravel/PHP debugging.
• Non-Invasive Design: The package extends Craft’s existing debug output mechanisms (e.g., Craft::$app->getLogger()) without requiring deep architectural changes. This aligns well with Craft’s modular plugin system.
• Performance Overhead: Minimal runtime impact during development (only active when Ray is running locally). Production use should be gated behind feature flags or environment checks to avoid unintended data leakage.

Integration Feasibility

• CraftCMS Compatibility: Officially supports Craft 4.x (based on README and release date). Compatibility with Craft 3.x is untested but likely feasible with minor adjustments (e.g., dependency version pinning).
• Ray Dependency: Requires a local Ray installation (desktop app) for debugging. This adds a tooling dependency but is offset by Ray’s cross-framework utility (e.g., JavaScript/Python integration).
• Plugin vs. Standalone: Can be deployed as a standalone plugin or embedded within a custom module. Plugin route is recommended for reusability across projects.

Technical Risk

• Ray Licensing: Free tier limits messages/session (20). Teams may need to budget for licenses if scaling debugging needs (e.g., high-frequency logging in CI/CD).
• Data Privacy: Debug output sent to Ray includes sensitive data (e.g., SQL queries, request payloads). Must enforce:
  • Environment-based gating (e.g., APP_ENV=local).
  • Sanitization of PII (e.g., passwords, tokens) via Craft’s Craft::$app->getSecurity()->hashData().
• Network Dependency: Ray requires a local network connection to the Ray server (port 8080 by default). Firewall/VPN environments may need configuration.
• Legacy Craft Projects: Older Craft 3.x projects may require polyfills for newer PHP features (e.g., named arguments) used by Ray’s PHP client.

Key Questions

1. Debugging Workflow:

   • How will Ray’s output be correlated with Craft’s native logs (e.g., storage/logs/) for post-mortem analysis?
   • Will teams use Ray primarily for development or also in staging (with strict data filtering)?

2. Tooling Alignment:

   • Does the team already use Ray for Laravel/PHP? If not, what’s the justification for adopting it over Craft’s built-in tools (e.g., devMode, Xdebug)?
   • How will Ray’s themes/branding be customized to match Craft’s admin panel?

3. Scaling:

   • What’s the expected volume of debug messages in high-traffic environments? Will sampling or rate-limiting be needed?
   • How will Ray’s performance profiling (e.g., execution pauses) interact with Craft’s queue workers or CLI commands?

4. Security:

   • Are there plans to extend Ray’s MCP server for Craft-specific data (e.g., element queries, template variables)? If so, how will authentication be handled?
   • Will Ray’s output be logged persistently (e.g., to a database) for auditing?

5. Maintenance:

   • Who will manage Ray license renewals and updates to the spatie/craft-ray package?
   • How will breaking changes in Ray or Craft be mitigated (e.g., via a wrapper layer)?

Integration Approach

Stack Fit

• CraftCMS Ecosystem:

  • Core Integration: Hooks into Craft’s Event::LOG_MESSAGE and Event::REQUEST_HANDLE events to intercept debug output. Works alongside existing plugins like craft/log-viewer.
  • Template Debugging: Extends Twig debugging with Ray’s ray() helper (e.g., {{ _debug|ray }} for template variables).
  • CLI Support: Captures debug output from Craft’s console commands (e.g., ./craft migrate/all).

• Ray Compatibility:

  • Uses Ray’s PHP client under the hood, ensuring consistency with existing Ray workflows (e.g., variable inspection, performance timers).
  • Supports Ray’s MCP (Message Control Protocol) for AI-assisted debugging (if enabled).

• Laravel Synergy:

  • If the project uses Laravel alongside Craft (e.g., via craftcms/cms or custom integration), Ray’s Laravel support can be unified with Craft’s output via a shared Ray configuration.

Migration Path

1. Pilot Phase:

   • Install spatie/craft-ray in a non-production Craft environment.
   • Test with a single plugin/module to validate output fidelity and performance.
   • Compare Ray’s debugging experience against Craft’s devMode and Xdebug.

2. Gradual Rollout:

   • Phase 1: Enable Ray for template debugging (Twig) and basic logging.
   • Phase 2: Integrate with Craft’s event system for deeper debugging (e.g., element queries, service layers).
   • Phase 3: Extend to CLI commands and queue workers (if needed).

3. Configuration:

   • Centralize Ray settings in config/ray.php (merge with Craft’s config/general.php for environment-specific toggles).
   • Example:

     return [
         'enabled' => getenv('RAY_ENABLED') === 'true',
         'channels' => ['*'], // Whitelist/blacklist channels
         'sanitize' => [
             'fields' => ['password', 'apiToken'],
         ],
     ];
     

Compatibility

Sequencing

1. Prerequisites:

   • Install Ray desktop app (myray.app).
   • Ensure PHP 8.1+ and Craft 4.x are in use.

2. Installation:

   composer require spatie/craft-ray
   ./craft install/plugin spatie-craft-ray
   

3. Configuration:

   • Publish the config file: ./craft vendor-publish/spatie/craft-ray.
   • Enable in config/app.php:

     'modules' => [
         'spatie-craft-ray' => [
             'enabled' => true,
         ],
     ],
     

4. Testing:

   • Verify output in Ray for:
     • Twig templates ({{ someVar|ray }}).
     • Controller actions (ray($this->request->getBody())).
     • Service layers (ray(Craft::$app->getElements()->getContentById(1))).

5. Production Readiness:

   • Disable in non-development environments via .env:

     RAY_ENABLED=false
     

   • Add to composer.json scripts for CI/CD:

     "scripts": {
         "debug:ray": "RAY_ENABLED=true craft serve"
     }
     

Operational Impact

Maintenance

• Package Updates:

  • Monitor spatie/craft-ray for updates (MIT license allows forks if needed).
  • Ray’s PHP client may require occasional updates; test compatibility with Craft’s PHP version.

• Configuration Drift:

  • Centralize Ray settings in Craft’s config system to avoid hardcoded values.
  • Use environment variables for sensitive toggles (e.g., RAY_ENABLED).

• Deprecation:

  • Ray’s PHP client may evolve; ensure backward compatibility by pinning versions in composer.json:

    "require": {
        "spatie/craft-ray": "^1.0",
        "spatie/ray": "^1.12.0"
    }
    

Support

• Troubleshooting:

  • Common issues:
    • Ray not receiving messages → Check RAY_ENABLED and firewall rules (port 8080).
    • Performance slowdowns → Disable Ray in production or use sampling.
  • Debugging Ray itself: Use ray() to inspect Ray’s internal state (e.g., ray(Ray::getClient()->getConfig())).

• Documentation:

  • Create internal runbooks for:
    • Enabling Ray in CI/CD (e.g., GitHub Actions).
    • Sanitizing sensitive data before sending to Ray.
  • Link to official Craft-Ray docs.

• Escalation Path:

  • For Ray-specific issues, engage Spatie’s support (paid license required for