Announcing x-ray
Tags: php, tooling, debugging, news
Published: 2021-09-17 11:01:41

![x-ray logo](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/py2ejdn4ul2qzy3hw360.png)

## Announcing x-ray

I'm proud to announce the initial release of the [`spatie/x-ray`](https://github.com/spatie/x-ray) package for [Ray](https://myray.app).  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](https://github.com/spatie/x-ray).

### 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:
```bash
./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](https://github.com/spatie/x-ray) 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`](https://github.com/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](https://github.com/permafrost-dev/code-snippets).

#### 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](https://github.com/nunomaduro/collision/blob/stable/src/Highlighter.php).  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):

- [Freek Van der Herten](https://github.com/freekmurze)
- [Alex Vanderbist](https://github.com/AlexVanderbist)  
- [Tom Witkowski](https://github.com/Gummibeer)
- [Spatie](https://github.com/spatie)
- [Nuno Maduro](https://github.com/nunomaduro)