I'm proud to announce that Steve Bauman and our team at Spatie have released a new tool called spatie/globay-ray. When installed, you'll be able to use dd, dump and ray functions in any PHP file on your system.

Why we have created this

Even though we are all professional developers, we all make mistakes from time to time, which doesn't make you an amateur. Luckily in the PHP ecosystem, we are blessed with many tools that can help you debug.

Xdebug is a wonderful tool to use for hunting down bugs. Personally, I only use it for difficult bugs where I want to see the whole state of my app. For other kinds of bugs, I tend to use Ray, and Symfony's dump() and dd() functions.

In regular Laravel and Symfony projects, dump() and dd() are always available. I tend to always install one of the ray packages in each application so ray() is available too.

But I'm not always working in a project context. I sometimes use CodeRunner to run small bits of JavaScript and PHP quickly, and sometimes I find myself creating a simple PHP script that is a single file. In those instances, debugging functions like dump(), dd() and ray() are not available.

Our tool spatie/global-ray solves that problem. When installed, those debugging functions will work in every PHP file. And as a bonus: to use Ray, you don't need to install a package in a project anymore.

It might sound strange, but not each PHP community has embraced dependencies via Composer yet. An example is the WordPress community, where it's relatively common not to use Composer by default in a project. Installing global-ray is probably the easiest way of getting ray() to work in a WordPress environment.

How it works under the hood

Getting started with global-ray is very easy. Just issue these two commands:

composer global require spatie/global-ray
global-ray install

That install command will register a script called global-ray-loader.php in the auto_prepend_file directive in your php.ini. This will make PHP execute that script each time a PHP starts.

In that script, we will load two phar files: one that contains the symfony phar dumper (exposing dd and dump), and another phar that contains the Ray package. By shipping these packages as phars, we minimise the risk that you'll get dependency issues while globally installing spatie/global-ray.

With global-ray installed, let's now try to use it. Here's a one-line script where we use ray().

Wonderful, right?

When installed globally, ray() only has the framework-agnostic functions. To use framework-specific functionality, such as viewing queries in Laravel, or displaying emails in WordPress, you should still install the relevant package or library. Global Ray will detect a framework-specific package installed and load that one.

In closing

Global Ray seems like a simple tool (and at its core, it is), but a lot of minor problems had to be solved to get it working correctly. Creating phars using GitHub Actions, getting the autoloaders not to collide, ... took some time.

I want to thank Steve Bauman, who started development and helped a lot with getting this package to work.

If you don't know Ray yet, I highly encourage you to check it out. I can guarantee it will help you debug stuff faster.

Do also check out this extensive list of open source stuff that my colleague and I and Spatie have previously released.