Developers ‐ websites ‐ setting up xdebug for profiling

Install xdebug

use php-8.x in Dockerfile, e.g. replace php:7-4 for the runtime container with:

# Site
FROM php:8.3-apache

exec a shell on the container:

apt update
apt install git-all
curl -fL --output /tmp/pie.phar https://github.com/php/pie/releases/latest/download/pie.phar \
  && mv /tmp/pie.phar /usr/local/bin/pie \
  && chmod +x /usr/local/bin/pie
pie install xdebug/xdebug
echo xdebug.mode=profile > /usr/local/etc/php/conf.d/xdebug-profile.ini
apachectl restart

Run xdebug

Basically, look for the X-Xdebug-Profile-Filename http header to get the profile and download the cachegrind file generated from /tmp in the container. I used https://sourceforge.net/projects/qcachegrindwin/ to view results on Windows.

For example, here's a test run (or you could run interactive in browser if you prefer, and use devtools to get the header):

$ curl -sS -D - help.keyman.com.localhost -o /dev/null
HTTP/1.1 200 OK
Server: nginx/1.25.3
Date: Thu, 18 Jun 2026 09:28:09 GMT
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
X-Powered-By: PHP/8.3.31
X-Xdebug-Profile-Filename: /tmp/cachegrind.out.10474
Vary: Accept-Encoding

$ docker cp help-keyman-com-app:/tmp/cachegrind.out.10474 /c/temp/cachegrind.out.10474

https://xdebug.org/docs/profiler