xdebug-profiling

Environment

All commands run via ssh web. Xdebug output is stored inside the web container at /tmp/xdebug/. Use $DDEV_DOCROOT for paths.

Two Modes

Mode	Use for	Output	Analysis
trace	Debug errors, trace execution path	.xt files (function calls, args, returns)	Read trace, find error origin
profile	Performance bottlenecks, slow pages	cachegrind.out.* files	Find slowest/most-called functions

Setup (run once per session)

ssh web mkdir -p /tmp/xdebug

# Verify Xdebug is available — expected output: "xdebug"
ssh web php -m | grep -i xdebug

If the grep output is EMPTY, do not invent paths: ask the user to run ddev xdebug on on the HOST, then re-check.

After EVERY config change below, verify it took effect:

ssh web php -i | grep "xdebug.mode"

Workflow A: Trace Mode (Debug Errors)

Step 1: Enable trace

ssh web bash -c "
  PHP_VER=\$(php -r 'echo PHP_MAJOR_VERSION.\".\".PHP_MINOR_VERSION;')
  cat > /etc/php/\${PHP_VER}/fpm/conf.d/99-xdebug-custom.ini <<'EOF'
xdebug.mode=trace
xdebug.start_with_request=trigger
xdebug.output_dir=/tmp/xdebug
xdebug.trace_format=1
xdebug.collect_return=1
xdebug.collect_assignments=1
xdebug.trace_output_name=trace.%t.%p
EOF
  kill -USR2 \$(pgrep -o php-fpm)
"

Step 2: Trigger the request

# Via curl inside web container (or Playwright with ?XDEBUG_TRIGGER=1)
ssh web curl -s -b 'XDEBUG_TRIGGER=1' 'http://localhost/the-page' -o /dev/null -w '%{http_code}'

Step 3: Analyze the trace

3a. Write the analyzer script ONCE per session (copy this block EXACTLY — the quoted 'EOF' prevents any variable expansion):

ssh web "cat > /tmp/analyze-trace.php" <<'EOF'
<?php
// Usage: php /tmp/analyze-trace.php /tmp/xdebug/trace.XXXX.xt
$lines = file($argv[1]);
$entries = []; $calls = [];
foreach ($lines as $line) {
  $f = explode("\t", trim($line));
  if (count($f) < 5) continue;
  if ($f[2] === '0' && isset($f[5])) {
    $entries[$f[1]] = ['name' => $f[5], 'start' => (float) $f[3], 'file' => $f[8] ?? '', 'line' => $f[9] ?? ''];
  }
  elseif ($f[2] === '1' && isset($entries[$f[1]])) {
    $d = (float) $f[3] - $entries[$f[1]]['start'];
    $n = $entries[$f[1]]['name'];
    if (!isset($calls[$n])) {
      $calls[$n] = ['count' => 0, 'total' => 0, 'file' => $entries[$f[1]]['file'], 'line' => $entries[$f[1]]['line']];
    }
    $calls[$n]['count']++;
    $calls[$n]['total'] += $d;
  }
}
uasort($calls, fn($a, $b) => $b['total'] <=> $a['total']);
printf("%-45s %6s %10s %s\n", 'Function', 'Calls', 'Time(s)', 'Location');
echo str_repeat('-', 90) . "\n";
foreach (array_slice($calls, 0, 25) as $n => $d) {
  printf("%-45s %6d %10.4f %s:%s\n", substr($n, 0, 45), $d['count'], $d['total'], basename($d['file']), $d['line']);
}
EOF