Announcing x-ray

#php #tooling #debugging #news

Announcing x-ray

I'm proud to announce the initial release of the spatie/x-ray package for Ray. The x-ray package provides a command-line utility that finds and displays all calls to ray(), rd(), and other functions from the spatie/ray family of packages. Currently, it only supports PHP projects.

Note: x-ray only displays the location of calls to ray(). It never modifies any files.

For more information and documentation, visit the Github project.

Using the package

You can install x-ray with composer:
composer require spatie/x-ray --dev

By default, the vendor and node_modules directories are ignored, and if your project has a .gitignore file, those entries are ignored as well.

To get started, simply run the script and provide a path or filename to scan:

./vendor/bin/x-ray . --summary

If any results are found, there will be output similar to the following:

 ❱ scanning for ray calls...
  34/34 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 ❱ scan complete.

+-------------------------------+-------------+
| Filename                      | Call Count  |
+-------------------------------+-------------+
| ./test1.php                   | 6           |
| ./test2.php                   | 3           |
| ./tests/fixtures/fixture1.php | 1           |
+-------------------------------+-------------+

❗Found 10 calls in 3 files.

If you've been keeping your code clean and free of calls to ray() once you're done debugging, you might see the following:

 ❱ scanning for ray calls...
 ❱ scan complete.
 ✔ No references to ray were found.

Want to see an excerpt of the code where the call was found?

Use the --snippets flag:

./vendor/bin/x-ray ./tests --snippets
 ❱ scanning for ray calls...
 18/18 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 ❱ scan complete.

 ❱ Found: ray
 ❱ File : ./tests/fixtures/fixture1.php:2

       1▕  <?php
 ❱❱    2▕      ray('12345');
       3▕  
       4▕      echo strtolower('TEST') . PHP_EOL;
       5▕  
       6▕      echo strtoupper('test') . PHP_EOL;

 ❗Found 1 call in 1 file.

Visit the github project to see all available options, how to use x-ray in an automated fashion, and more.

Background

This project originally was required because I'm using Ray at my day job and for various reasons, calls to ray() cannot be committed or merged (and definitely not into production).

As you can guess, this happened a few times, and I realized that we needed a way of preventing it from happening again. Ideally, it could be automated in a git hook and/or Github workflow. From this, the idea for creating x-ray was born.

Some notes on development

Code Snippets

When first creating x-ray, I felt it was necessary to display an excerpt of the source code location where the call to ray() was found. Rather than roll my own solution, I extracted the excellent Snippet class from spatie/backtrace into a package. From there it was a simple matter of adding functionality for multi-line line selections and a few other minor changes. You can view the final permafrost-dev/code-snippets package and its documentation on Github.

Syntax Highlighting

I also felt from the beginning that the code snippets should be syntax highlighted in the console output. After a decent attempt at creating basic syntax highlighting, I again went with the tried-and-true method of extracting existing code from a project. In this case, the original source code came from nunomaduro/collision. Again, with some modifications, it suited my needs perfectly.

In closing

A number of people contributed input and feedback, code reviews, thoughts, and generally offered support and help, not to mention beta testing along the way. I truly appreciate the help of everyone and couldn't have created this package without them. Thank you to (in no particular order):