Using Ray in WordPress Development

If you are not debugging your WordPress code with Ray you are missing out.

The most common way of debugging WordPress code is dumping data using var_dump and print_r. However, this method is very limiting and dumping the data on screen may break your application. Ray allows to dump the data to desktop application, which means that the dumped data does not interfere with your application.

What is Ray?

Ray originates from the Laravel community and is developed by Spatie but this does not mean that you need to learn Laravel if you want to use Ray. In fact, Ray has very good support for WordPress and can show you executed queries, sent mails and more.

Ray is extremely easy to use and all you have to do is use the debug data as argument in the ray() function:

function myAwesomeFunction() {

    // Send strings, arrays, object,...
    $string = 'My first debug Item';
    ray($string);

    // Send as much as you want
    $array = [
        'a' => 1,
        'b' => ['c' => '????'],
    ];
    ray($array);

    // Apply a color
    // and use Ray's color filters
    $string2 = 'A green statement';
    ray($string2)->green();

}

In line 5, 12 and 17 we pass a string, array and string respectively to ray(), which are then output to the Ray app. Note that in line 17 we furthermore use the green() method to give the entry a green label which can be seen in the screen dump of Ray below.

Ray does not interfere with your website which is a big plus. Using var_dump in the frontend will change the content and that will be af problem in the midle of json, XML, JavaScript etc. When you use Ray the site will function as normal but you will get the debug info you need.

That’s not all. You can also debug remote installations where Ray is installed because Ray will forward the data via SSH to your local machine.

So what’s not to like? Well, Ray unfortunately is not free but it only cost 48 USD per year and this tool is a life saver.

Installing Ray

To get started you need to:

• Download the Ray app and register it with a license key
• Install Ray in project code and globally in you dev environment
• Start using Ray!

Global installation of Ray

I reccomend that you start by installing Ray globally in you dev environment. This will make ray() available in all your PHP files on your system.

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

Installing Ray in your WordPress app

If you want to use the WordPress specific capabilities of Ray, you have to install wordpress-ray in your WordPress app.

This can be done by installing the “Spatie Ray” plugin available at WordPress.org. However, this only allows you to debug the current theme. I you want to debug all plugins you need to install the plugin in /wp-content/mu-plugins. This manual step could be handled by the plugin but at the time of writing you need to do it yourself.

Because of this manul installattion i prefer to just clone the WordPress Ray repository in the /wp-content/mu-plugins. To this you have to run the following command in the mu-plugins directory:

git clone git@github.com:spatie/wordpress-ray

Then create ray-loader.php within /wp-content/mu-plugins with the following content:

require WPMU_PLUGIN_DIR.'/wordpress-ray/wp-ray.php';

Activate Ray in wp-config.php

You wont get any debug data from WordPress Ray until you set WP_ENVIRONMENT_TYPE as local in your wp-config.php:

define( 'WP_ENVIRONMENT_TYPE', 'local' );

If you need to debug remotely on your prouction server you have to set the environt to local while debugging or you wont get any data in the Ray app. This alsp means that you can deactivate Ray on you production site by setting WP_ENVIRONMENT_TYPE as prod or not setting it at all.

Don’t forget to remove ray()

If you have ray() in your code without having Ray installed in your project or globally your code will get a fatal error. This is not a problem if you are working on your own site but if you are developing a theme or plugin for public use you can not expect Ray to be installed.

Please keep this in mind.

Advanced usage of Ray

The ray() function has a lot of methods which you can find in the documentation but I just want to show you one of them.

Below I have added ray()->pause() in line 15 of myAwesomeFunction(), which is a breakpoint that pauses the code execution until you click continue in the Ray app.

function myAwesomeFunction() {

    // Send strings, arrays, object,...
    $string = 'My first debug Item';
    ray($string);

    // Send as much as you want
    $array = [
        'a' => 1,
        'b' => ['c' => '????'],
    ];
    ray($array);

    // Let's set a breakpoint
    ray()->pause();

    // Apply a color
    // and use Ray's color filters
    $string2 = 'A green statement';
    ray($string2)->green();

}

As you can se below the code execution has been pased:

Ray is not Xdebug but it does so much more than var_dump and print_r and it is one of my most frequently used tools. It’s not free but the 48 USD is nothing compated to the hours of debugging it has saved me.