Smithery is now a part of Arcade.dev! Read more in our announcement here
PHP debugging and analysis tools using Xdebug. Use when asked to trace, debug, profile, or analyze coverage of PHP code.
Non-invasive PHP debugging and analysis tools. No var_dump() or code modification needed.
Tools are installed globally via composer. Use absolute paths:
| Tool | Path |
|---|---|
| xtrace | ~/.composer/vendor/bin/xtrace |
| xstep | ~/.composer/vendor/bin/xstep |
| xprofile | ~/.composer/vendor/bin/xprofile |
| xcoverage | ~/.composer/vendor/bin/xcoverage |
| xback | ~/.composer/vendor/bin/xback |
| xcompare | ~/.composer/vendor/bin/xcompare |
| xrepl | ~/.composer/vendor/bin/xrepl |
| User Request | Tool |
|---|---|
| Trace, execution flow, show function calls | xtrace |
| Step debugging, breakpoints, inspect variables, track variable changes | xstep |
| Profile, performance, bottlenecks, slow code | xprofile |
| Coverage, test coverage, which lines tested | xcoverage |
| Backtrace, call stack, how did we get here | xback |
| Compare variable states across two runs, normal vs edge case, compare with git branch | xcompare |
| Interactive debugging, REPL, step manually (human-friendly) | xrepl |
The word "trace" can mean different things:
xtrace (records execution from start to finish)xback (shows call stack at a point)xstep (records N steps from a breakpoint, JSON output)xrepl (human-friendly REPL session, not JSON)Trace execution forward from start to finish. Captures complete execution flow, function calls, parameters, and timing data.
Output: Text by default; --json gives JSON with a schema URL for semantic details and AI analysis strategies.
Key fields: {lines, functions, max_depth, db_queries}
~/.composer/vendor/bin/xtrace [--json] [--context=TEXT] [--include-vendor=PATTERNS] -- command
~/.composer/vendor/bin/xtrace --context="Debug login" -- php login.php
~/.composer/vendor/bin/xtrace --context="Test analysis" -- vendor/bin/phpunit tests/UserTest.php
~/.composer/vendor/bin/xtrace --include-vendor="bear/*" -- php app.php
Stop at breakpoint, step forward N times, record variable changes at each step. See how variable values affect branching ("this variable was X, so it went into this branch").
Output: Slim, deduplicated JSON with a $schema URL — fields you might expect inline can live elsewhere, so read the linked schema to interpret the structure and reconstruct variable state. The schema is the source of truth; do not infer the format from examples.
~/.composer/vendor/bin/xstep --break=file.php:line --steps=N [--context=TEXT] [--include-vendor=PATTERNS] -- command
--break=file.php:line - Single breakpoint location--break=file.php:line:condition - Conditional (e.g., $user==null)--steps=N - Step forward N times from breakpoint--watch=EXPR - Only record steps when expression value changes (can specify multiple times)# Step 20 times from line 42
~/.composer/vendor/bin/xstep --break="user.php:42" --steps=20 --context="Track auth" -- php user.php
# Conditional breakpoint
~/.composer/vendor/bin/xstep --break="user.php:15:\$id==null" --steps=10 -- php user.php
# Watch variable changes in loop
~/.composer/vendor/bin/xstep --break="loop.php:10" --watch="\$i" --steps=100 -- php loop.php
# Multiple watches
~/.composer/vendor/bin/xstep --break="app.php:25" --watch="\$user->getStatus()" --watch="count(\$items)" --steps=50 -- php app.php
Identify performance bottlenecks with precision data.
Output: Text by default; --json gives JSON with a schema URL. time_ms/memory_mb are measured from the cachegrind summary; bottlenecks is a structured array. Read the linked schema for the field shapes — don't infer the format here.
Key fields: {time_ms, memory_mb, bottlenecks}
~/.composer/vendor/bin/xprofile [--json] [--context=TEXT] [--include-vendor=PATTERNS] -- command
~/.composer/vendor/bin/xprofile --context="Optimize processing" -- php process.php
~/.composer/vendor/bin/xprofile --json -- php script.php
~/.composer/vendor/bin/xprofile --include-vendor="doctrine/*" -- php app.php
Collect code coverage data for PHPUnit or any PHP script. Shows only uncovered lines (compact output).
Output: Text by default; --json gives JSON with a $schema URL for semantic details.
Key fields: {summary: {coverage_percent, covered_lines, uncovered_lines}, uncovered: {file: [lines]}}
~/.composer/vendor/bin/xcoverage [--json] [--raw] [--include-vendor=PATTERNS] -- command
~/.composer/vendor/bin/xcoverage -- vendor/bin/phpunit # PHPUnit
~/.composer/vendor/bin/xcoverage --raw -- php script.php # Any PHP script (raw mode required)
~/.composer/vendor/bin/xcoverage -- vendor/bin/phpunit
~/.composer/vendor/bin/xcoverage --raw --include-vendor="bear/*,ray/di" -- php script.php
~/.composer/vendor/bin/xcoverage -- vendor/bin/phpunit --filter testMethod
Get call stack (backtrace) at a specific line. Shows "who called this?" - the chain of function calls that led to this point.
Output: JSON with $schema URL for semantic details.
Key fields: {script, breakpoint, stack: [{level, function, file, line}]}
~/.composer/vendor/bin/xback [--break=SPEC] [--depth=N] [--context=TEXT] -- command
~/.composer/vendor/bin/xback -- php script.php # First line
~/.composer/vendor/bin/xback --break=app.php:50 -- php app.php # At breakpoint
~/.composer/vendor/bin/xback --depth=20 -- php main.php # Deep trace
Compare variable states at the same breakpoint across two different executions. Useful for normal vs edge case inputs, success vs failure, or current code vs another git ref.
Output: JSON with $schema URL. diff contains {changed, unchanged, only_in_a, only_in_b} plus analysis_hints.
Key fields: {breakpoint, run_a, run_b, diff, analysis_hints}
# Mode 1: Compare two commands
~/.composer/vendor/bin/xcompare --break=FILE:LINE --run-a="CMD" --run-b="CMD" [--context=TEXT]
# Mode 2: Compare with another git ref
~/.composer/vendor/bin/xcompare --break=FILE:LINE --run="CMD" --compare-with=REF [--context=TEXT]
--label-a / --label-b - Labels for run A/B (default: command or 'HEAD'/ref name)--steps=N - Steps to record after breakpoint (default: 1)--include-vendor - Include vendor packages in trace# Normal vs edge case input
~/.composer/vendor/bin/xcompare --break=src/Calculator.php:25 \
--run-a="php calc.php 10" --run-b="php calc.php 0" \
--context="Compare division behavior with normal vs zero input"
# Authentication success vs failure
~/.composer/vendor/bin/xcompare --break=src/Auth.php:42 \
--run-a="php login.php valid_user" --run-b="php login.php invalid_user" \
--context="Compare authentication flow"
# Current code vs main branch
~/.composer/vendor/bin/xcompare --break=src/Calculator.php:25 \
--run="php calc.php 10" --compare-with=main \
--context="Compare current implementation vs main"
Note: --run-a, --run-b, and --run are executed through the shell — only pass trusted input.
Human-friendly interactive debugging session with breakpoints and variable inspection. Unlike the other tools, xrepl is an interactive session rather than one-shot JSON output — for AI-driven analysis, prefer xstep.
~/.composer/vendor/bin/xrepl --break=FILE:LINE [--include-vendor=PATTERNS] -- command
s - Step into functiono - Step over lineout - Step out of functionc - Continue executionp <var> - Print variable (e.g., p $user)bt - Show backtracel - Show current location (stack and variables)q - Quit debugger# Break at line 42 and debug interactively
~/.composer/vendor/bin/xrepl --break="script.php:42" -- php script.php
# Conditional breakpoint
~/.composer/vendor/bin/xrepl --break="user.php:15:\$id==null" -- php user.php
| Option | Description |
|---|---|
--json |
AI-optimized JSON output |
--context=TEXT |
Add description for AI analysis |
--include-vendor=PATTERNS |
Include vendor packages |
By default, vendor code is excluded to focus on your code. Use --include-vendor when needed:
--include-vendor="bear/*" # Include specific framework
--include-vendor="bear/*,ray/di" # Multiple packages
--include-vendor="*/*" # Include all vendor (framework debugging)
