spatie / x-ray
Quickly scan source code for calls to Ray
Fund package maintenance!
permafrost-dev
spatie
Installs: 112 036
Dependents: 30
Suggesters: 0
Security: 0
Stars: 75
Watchers: 6
Forks: 8
Open Issues: 0
Requires
- php: ^8.0
- permafrost-dev/code-snippets: ^1.2.0
- permafrost-dev/php-code-search: ^1.10.5
- symfony/console: ^5.3|^6.0|^7.0
- symfony/finder: ^5.3|^6.0|^7.0
- symfony/yaml: ^5.3|^6.0|^7.0
Requires (Dev)
- phpstan/phpstan: ^0.12.92
- phpunit/phpunit: ^9.5
- spatie/phpunit-snapshot-assertions: ^4.2
README
This package can quickly scan source code for calls to ray()
, rd()
, Ray::*
, and ->ray()
helper methods from the spatie/ray and spatie/laravel-ray packages.
The primary use case is when calls to ray()
cannot be left in source code before deploying, even if ray is disabled. This package does NOT remove the calls, it simply displays their locations so they can be removed manually.
The exit code of the x-ray
command is zero if no ray calls are found, and non-zero if calls are found. This allows the package to be used in an automated environment such as Github Workflows.
Visit myray.app for information on downloading the Ray debugging app.
Installation
composer require spatie/x-ray --dev
Usage
Specify one or more valid path names and/or filenames to scan:
./vendor/bin/x-ray ./app/Actions/MyAction.php ./app/Models/*.php ./tests --snippets
Display a summary table of the located calls within ./src
and ./tests
while also ignoring some files:
./vendor/bin/x-ray \
--summary \
--ignore src/MyClass.php \
--ignore 'test/fixtures/*.php' \
./src ./tests
Display each filename & pass/fail status, along with compact results:
./vendor/bin/x-ray ./app --compact --verbose
Available Options
Configuration files
Create a file named x-ray.yml
or x-ray.yml.dist
in the root directory of your project to configure the package.
If the configuration file exists, it must have the root sections functions
and paths
.
Each section may have an ignore
or include
item, both, or neither. Each item contains an array of strings, and includes override ignores if an entry exists in both. Add a *
item to ignore or include all matches (make sure to quote the asterisk).
By default, functions.include
matches the ray
and rd
functions.
functions: include: - '*' paths: include: - 'tests/fixtures/*' ignore: - tests - 'SettingsTest.php'
Automation
x-ray
was designed to be used not only as a manual utility, but in conjunction with automation tools.
Github workflows
You may use x-ray
within a github workflow to help ensure you don't commit any calls to ray()
.
The following example workflow runs unit tests with PHPUnit and then runs x-ray
:
name: run-tests on: push: branches: - main pull_request: jobs: test: runs-on: ${{ matrix.os }} strategy: fail-fast: true matrix: os: [ubuntu-latest] php: [8.3, 8.2, 8.1] name: P${{ matrix.php }} - ${{ matrix.os }} steps: - name: Checkout code uses: actions/checkout@v4 - name: Setup PHP uses: shivammathur/setup-php@v2 with: php-version: ${{ matrix.php }} extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick, fileinfo coverage: pcov - name: Setup problem matchers run: | echo "::add-matcher::${{ runner.tool_cache }}/php.json" echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json" - name: Install dependencies run: composer update --prefer-stable --prefer-dist --no-interaction - name: Execute tests run: ./vendor/bin/phpunit - name: Check for ray calls run: ./vendor/bin/x-ray . --compact
Git hooks
In some cases you may want to use a git pre-commit
hook to avoid commiting any ray()
calls:
#!/bin/sh echo "Checking for ray() calls...\n" x-ray -s . rayScanExitCode=$? printf '%*s\n' "${COLUMNS:-$(tput cols)}" '' | tr ' ' - localPreCommitExitCode=0 if [ -e ./.git/hooks/pre-commit ]; then ./.git/hooks/pre-commit "$@" localPreCommitExitCode=$? fi exit $rayScanExitCode || $localPreCommitExitCode
You can also use x-ray
with husky in your package.json
configuration:
... "husky": { "hooks": { "pre-commit": "lint-staged && .x-ray -s ." } }, ....
Screenshots
Various screenshots can be viewed in the docs.
Testing
./vendor/bin/phpunit
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
License
The MIT License (MIT). Please see License File for more information.