Tracing and Profiling with Xdebug
Besides the step debugger, Xdebug can record what your code did after the fact:
tracemode writes every function call, argument, and timing to atrace.*.xtfile.profilemode writes a cachegrind file you can open in Speedscope, KCachegrind, QCachegrind, or PhpStorm.
When started with --xdebug, Playground enables the debug and develop
modes by default. Use --php-ini to enable additional modes or change any
php.ini setting, including
Xdebug settings. Values passed this way
override both Playground's and Xdebug's defaults.
Recording a trace and a profile
Trace and profile files are written to xdebug.output_dir, which is a path in
Playground's virtual filesystem. Mount a directory of your own there so the
files survive after the request ends:
mkdir -p ./xdebug-output
npx @wp-playground/cli@latest server \
--xdebug \
--mount ./xdebug-output:/xdebug-output \
--php-ini xdebug.mode debug,develop,trace,profile \
--php-ini xdebug.start_with_request trigger \
--php-ini xdebug.output_dir /xdebug-output \
--php-ini xdebug.trace_output_name trace.%u.%p \
--php-ini xdebug.profiler_output_name cachegrind.out.%u.%p
Then request the page you want to measure with the XDEBUG_TRIGGER parameter:
curl "http://127.0.0.1:9400/wp-json/wp/v2/posts?XDEBUG_TRIGGER=1"
./xdebug-output now holds one trace.*.xt file and one cachegrind.out.*
file for that request. Drop the cachegrind file into Speedscope to see where
the time went, and open the trace file in your editor to follow the call path.
Record on demand, not on every request
xdebug.start_with_request=trigger is the setting that makes recording opt-in.
Nothing is written until a request carries XDEBUG_TRIGGER as a GET
parameter, a POST parameter, or a cookie.
This matters because the files are large. One WordPress front-page request
produces a trace of about 135 MB and a cachegrind file of about 22 MB. With
xdebug.start_with_request=yes, every request, including every admin-ajax
and REST call your browser makes, writes both files.
The trigger also starts the step debugger, so a Playground started this way only connects to your IDE on triggered requests.
Give every recording its own file name
By default, Xdebug can give two recordings the same file name, so a new
request can overwrite an earlier one. See
xdebug.trace_output_name
and
xdebug.profiler_output_name
for the default names.
Adding %u (timestamp with microseconds) to xdebug.trace_output_name and
xdebug.profiler_output_name keeps one file per request, as in the command
above. Running with --workers=1 also keeps the output predictable.
Using the library API
PHP reads php.ini before extension-specific ini files, so settings in
xdebug.ini take precedence over matching settings in php.ini. The
Playground CLI writes xdebug.* entries to xdebug.ini and all other entries
to php.ini. When using @php-wasm/node directly, pass the Xdebug ini path to
setPhpIniEntries():
import { PHP, PHP_EXTENSIONS_DIR, setPhpIniEntries } from '@php-wasm/universal';
import { joinPaths } from '@php-wasm/util';
import { mkdirSync } from 'node:fs';
import { loadNodeRuntime, createNodeFsMountHandler } from '@php-wasm/node';
const php = new PHP(await loadNodeRuntime('8.5', { extensions: ['xdebug'] }));
await setPhpIniEntries(
php,
{
'xdebug.mode': 'debug,develop,trace,profile',
'xdebug.start_with_request': 'trigger',
'xdebug.output_dir': '/xdebug-output',
'xdebug.trace_output_name': 'trace.%u.%p',
'xdebug.profiler_output_name': 'cachegrind.out.%u.%p',
},
joinPaths(PHP_EXTENSIONS_DIR, 'xdebug.ini')
);
mkdirSync('./xdebug-output', { recursive: true });
await php.mount('/xdebug-output', createNodeFsMountHandler('./xdebug-output'));
Call setPhpIniEntries() before the first request runs. PHP parses the ini
files once, on the first run, and ignores every later write.
Without the third argument, setPhpIniEntries() writes php.ini, and the
entries an extension ships keep winning over it. An entry you do not set
keeps its default value.
Starting a trace from PHP
Xdebug's own functions work too, and they need no trigger:
xdebug_start_trace('/xdebug-output/checkout');
do_the_slow_thing();
xdebug_stop_trace();
This is the narrowest option. It records one block of code instead of a whole request, which keeps the trace file small enough to read by hand.