Weave Code
Craft Ray Laravel Package
spatie/craft-ray
Send debug output from Craft CMS to Ray, Spatie’s desktop debugging app. Inspect arrays, HTML, queries, and more with a consistent API, measure performance, and pause execution. Great for fast feedback across PHP and other languages.
Easily debug CraftCMS projects
Frequently asked questions about Craft Ray
- How do I install spatie/craft-ray in a Craft CMS 4 project?
- Run `composer require spatie/craft-ray` in your project root. The package integrates via Craft’s plugin system—no manual configuration is needed unless you want to customize Ray’s behavior. Ensure you have Ray installed locally (download from [myray.app](https://myray.app/)) to receive debug output.
- Will this work with Craft CMS 3.x, or is it Craft 4.x only?
- The package is officially designed for Craft 4.x, but Craft 3.x compatibility *might* work with minor tweaks (e.g., dependency version pinning). Test thoroughly in a staging environment, as Ray’s PHP client uses newer PHP features. Check the [Craft 3 compatibility branch](https://github.com/spatie/craft-ray/tree/main) if available.
- Can I use ray() in Craft templates (Twig) like in Laravel?
- Yes! The package adds a `ray()` helper for templates. Use `{{ _debug|ray }}` to inspect variables or `{% ray variable %}` in Twig. Output appears in Ray’s UI instantly, just like Laravel’s `dd()` or `ray()`. Avoid sensitive data in templates—always gate usage with `{% if craft.app.environment.isDevelopment %}...{% endif %}`.
- How do I prevent debug data from leaking in production?
- Wrap `ray()` calls in environment checks: `if (craft()->getConfig()->getGeneral()->devMode) { ray($data); }`. Disable Ray’s server in production by setting `RAY_SERVER_HOST=0.0.0.0` in your `.env`. For extra safety, sanitize data with `craft()->getSecurity()->hashData()` before sending.
- Does spatie/craft-ray support performance profiling like Laravel’s `stopwatch()`?
- Yes! Use `ray()->stopwatch('operation_name')` to measure execution time, just like Laravel’s `stopwatch()`. Ray displays timers in its UI with start/stop controls. For Craft’s queue workers, profile them by calling `ray()->stopwatch()` at key stages—results appear in Ray’s performance tab.
- Can I customize Ray’s UI theme to match Craft’s admin panel?
- Ray supports [theming](https://myray.app/docs/themes) via CSS variables. Override Ray’s styles by creating a `ray.css` file in your project’s root and referencing it in Ray’s settings. For Craft-specific themes, extend the default Ray theme by targeting `.ray-theme-craft` classes. Check the [Ray docs](https://myray.app/docs/php/customization) for advanced styling.
- How does Ray’s output correlate with Craft’s native logs (storage/logs/)?
- Ray and Craft’s logs are independent, but you can cross-reference them by including timestamps or request IDs in both. Use `ray(craft()->getRequest()->getId())` to log the same ID in Ray and Craft’s logs. For post-mortem analysis, export Ray’s output to JSON (`ray()->export()`) and store it alongside Craft logs.
- What alternatives exist for debugging Craft CMS without Ray?
- Craft offers built-in tools like `devMode` (enables Twig debugging) and `craft log` (for structured logs). For advanced debugging, consider Xdebug with IDEs (PhpStorm) or Laravel’s `laravel-debugbar`. However, Ray stands out for its cross-language consistency, real-time UI, and AI-assisted debugging via MCP—ideal for teams using multiple frameworks.
- Will Ray’s performance pauses break Craft’s queue workers or CLI commands?
- Ray’s pauses (`ray()->pause()`) work in PHP scripts, including Craft’s CLI commands (e.g., `./craft migrate/all`). For queue workers, avoid pausing during long-running tasks—use `ray()->stopwatch()` instead for performance metrics. Test in staging to ensure pauses don’t disrupt async processes like `craft queue/run`.
- How do I handle Ray’s free-tier limits (20 messages/session) in a high-traffic project?
- Upgrade to a [Ray license](https://spatie.be/products/ray) for unlimited messages. For free-tier projects, implement sampling: `if (rand(0, 100) < 10) { ray($data); }` to limit output. Alternatively, use `ray()->group()` to batch related messages. Monitor usage via Ray’s stats panel to avoid hitting limits.
Weaver
How can I help you explore Laravel packages today?