spatie/ray sends PHP debug output to a desktop app

A desktop app, not a log aggregator

spatie/ray is a package that can be installed in any PHP application to send debug output to Ray, the desktop debugging app from Spatie, whose site is myray.app.

That distinction matters. Ray is not a hosted service that collects logs from your servers, and it is not a browser-based debugger. It is a desktop application, and the PHP package is the client that sends data to it. The README describes it as keeping the instant feedback you get from console.log() and dump(), while letting you use the same debugging syntax across Laravel, PHP, JavaScript and more frameworks and languages.

The same syntax across languages is the real proposition. A PHP developer who also writes JavaScript in the same product otherwise ends up with two different habits of inspecting state, and the mental overhead of switching is real. Ray's approach is that the call looks the same in each language, so the same mental model carries across.

The audience is therefore a developer with a local machine, running a local application, who wants a richer view of what the code is doing than a terminal dump gives. The repository is the PHP side of that; the JavaScript and other language clients live elsewhere.

The package itself is MIT licensed, and the credits name Freek Van der Herten as the primary author alongside all contributors.

What you can send, and the pause button

The feature list is short, and two of the items are more than they sound.

You can send anything you want to Ray, including HTML, arrays, queries, and Markdown files. That list covers the cases a plain var_dump handles badly. HTML arrives as rendered markup rather than a string of tags. Queries arrive in a form you can read. Markdown files, which in a PHP project are often documentation or a changelog, arrive as a document.

Then there is measurement and interruption. The README lists measuring performance and pausing execution in PHP. Pausing execution is the unusual one: a call that stops the request in the middle so you can look at the state of the process at that point, rather than inferring it from what the log printed on the way out. For a bug that only shows up under a particular code path, that is the feature that makes the app worth a licence.

The third item is the one that has changed most recently. The README says you can view and interact with output your AI sends to Ray using Spatie's MCP server. So the flow is now bidirectional in a sense: the AI agent in your editor writes to the same Ray window you are reading, and you can interact with what it produced. The theme support is the fourth item, which is cosmetic but is the kind of thing that determines whether a developer keeps a debugging tool switched on all day.

What the README does not describe is the transport between the PHP process and the desktop app, which is the detail you would need to know before deciding whether the package can talk to a remote machine or a container.

The trial limit and what a licence buys

The commercial terms are stated in a single sentence and they matter for how the tool is used. Download the free trial and you can send up to 20 messages each session. If you like it, you buy a licence to remove the trial limits.

Twenty messages per session is a meaningful constraint rather than a formality, and the way it bites depends entirely on how you work. A developer who uses Ray to inspect one failing request, reads the output, and closes the window will probably never reach the limit. A developer who has wired Ray into a feature flag, or who leaves log calls in the code while working on a larger change, will hit it quickly.

This also separates the two halves of the project in a way that is easy to miss. The PHP package is MIT licensed, so you can install it, use it, read it and modify it, and there is no licence fee for the code. The desktop application is the commercial part, and the trial limit applies to it.

The practical implication for a team is that the cost is per developer on the desktop, and the choice of whether to keep the calls in the code is a separate decision from whether the code is licensed.

Installing it, and running the package's own tests

The README does not give an install command, and it points to the documentation instead. The PHP documentation, including the vanilla PHP installation page, is at myray.app/docs/php, and the full documentation for using Ray with PHP is linked from the README.

That is a deliberate choice rather than an omission. The package can be installed in any PHP application, and the installation varies with the framework and with the version of PHP, so the instructions live in the docs site, which is versioned with the app rather than with the package.

One command is given in the README, and it is the one worth running first if you are evaluating the package:

composer test

That runs the package's own test suite, which is the fastest way to see the API surface the current version actually supports, since the README's feature list is a summary rather than an index. The repository has a tests directory and a phpunit.xml.dist, so the suite is a standard PHPUnit one.

For a team that wants to try Ray without changing any application code, the documentation's installation path is the place to start, and the package's changelog is linked from the README for what changed in each version.

How a Spatie package is laid out

The repository layout is a good template for what a well-maintained PHP package looks like, and it is worth reading even if you never install the package.

There is a src directory for the code, a tests directory, and a bin directory for the command line entry points the package installs. The composer.json describes the package, and the project uses PHPStan with a configuration file and a baseline file, which is the common pattern for a library that supports a range of PHP versions, where the baseline records the issues that are known and accepted rather than pretending they do not exist. The code style configuration is in a .php_cs.dist.php file, which is the older PHP CS Fixer convention, and the test configuration is phpunit.xml.dist.

The file that catches my eye is remove-ray-rector.php, at the top level of the repository. Rector is a tool that rewrites code automatically, and this file is a custom rule that removes Ray calls from a codebase. Its existence tells you how the maintainers expect the tool to be used: you add Ray calls while you are debugging, and then you have a mechanical way to take them back out again.

That is the answer to the obvious objection to any debug-instrumentation library, which is that you do not want debug calls in production code. A tool that ships a rule to remove them has thought about that objection.

The README also links a security policy, which matters for a package that opens a channel to a desktop application.

Where Ray does not fit

The strongest constraint is the one the licence section implies and the feature list does not mention: the receiver is a desktop application. A staging server, a CI pipeline or a container in production has no Ray window to send to, so a team that wants its debug output in a log pipeline rather than on a developer's screen has to look elsewhere.

The second constraint is the trial limit of 20 messages per session, which makes Ray awkward as an always-on instrumentation and comfortable as a targeted tool.

The third is that the interesting features are PHP-side. Sending HTML, arrays, queries and Markdown is what the package does, and the JavaScript and other language clients are separate packages with their own capabilities. The promise of one syntax across languages is real, but the richness of what you can send is not necessarily identical, and the README does not give a feature matrix. That is the check to make before committing to the idea of a uniform cross-language debugging vocabulary.

The fourth is simply the cost. The code is free, but the application is a paid product, and a team with many developers is making a per-seat decision. The AI integration through the MCP server, which is the newest feature, is also the one that depends on the current version of the app.

Licence, releases and the pace of maintenance

The licence is the MIT License, with a link to the licence file in the repository, and the copyright holder is Spatie. The package is on Packagist as spatie/ray.

The release history is regular and the version numbers move quickly. Version 1.48.0 came out on 2026-03-31, 1.47.0 on 2026-02-20 and 1.46.0 on 2026-02-06, which is a minor release every couple of weeks during that period. The last push to the repository was on 2026-06-29, and the repository is not archived.

A cadence like that has a practical implication for anyone depending on the package. Because the package is installed into applications that also carry a Laravel or Symfony dependency tree, a fast-moving package is one you pin deliberately rather than float. The CHANGELOG.md is linked from the README for exactly that purpose.

The project is run by Spatie, a company that publishes a family of PHP packages and the desktop app itself, so the package and the app move together. That is an advantage when a new app feature needs package support, and it is a consideration when the app is commercial and the package is not: the two have different licensing terms, and it is worth being clear about which half of the workflow is free.

Editorial conclusion

spatie/ray fits a PHP developer who has outgrown console logging, especially one working across PHP, Laravel and JavaScript in the same application, and who wants the same call to work in each. It is the wrong tool for a headless environment, since the receiver is a desktop application, and it is the wrong tool for a team that cannot ship a commercial licence for the app, because the free trial is capped at 20 messages per session. Before adopting it, check that the syntax you need exists in the PHP package rather than only in the JavaScript one, plan how you will strip the calls before a production deploy, and read the composer test command in the repository, since the package's own suite is the fastest way to see the supported API surface.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. spatie/ray on GitHub