Skip to content

Xdebug

Jump to bottom
Joost van Dijk edited this page Jan 16, 2019 · 5 revisions

If Xdebug is enabled in the PHP interpreter, it will connect to a debug client (e.g. PhpStorm or debugclient) to start a debug session, using the DBGp protocol.

Check your Xdebug installation

php --modules | grep xdebug

If Xdebug is not enabled, edit your php.ini file and add

zend_extension="/path/to/xdebug.so"

Use a separate .ini file with php --php-ini when performance degradation due to Xdebug affects existing php processes.

Check your Xdebug configuration

php --info |grep ^xdebug -A9

Change your Xdebug configuration

  • edit file php.ini
  • overrule the .ini file with php --define
  • set environment variable XDEBUG_CONFIG

For instance, to change the remote_port from the 9000 default to 9001:

$ php --define xdebug.remote_port=9001 --info | grep remote_port
xdebug.remote_port => 9001 => 9001
$ XDEBUG_CONFIG="remote_port=9001" php --info | grep remote_port
xdebug.remote_port => 9001 => 9000
XDEBUG_CONFIG => remote_port=9001
$_SERVER['XDEBUG_CONFIG'] => remote_port=9001

Test with debugclient

A simple DBGp client is included with Xdebug

git clone git://github.com/xdebug/xdebug.git
cd xdebug/
cd debugclient/
./buildconf 
./configure --with-libedit
make
./debugclient

The client will start listening on port 9000 (override with -p)

Test

Start the built-in HTTP server with a test script

touch index.php
php --define xdebug.remote_enable=On --define xdebug.remote_autostart=On -S 0:8080 index.php

Start the debug client

./debugclient -1

Trigger a debug session

curl http://0:8080/

Configure remote debugging using a debug client

  • Xdebug will connect to a debug client if xdebug.remote_enable is On.
  • Xdebug will initiate a debug connection when the script starts (req), or on error (jit). Specify with xdebug.remote_mode
  • If xdebug.remote_connect_back is On, Xdebug tries to determine the client IP from HTTP headers specified by xdebug.remote_addr_header, defaulting to X_FORWARDED_FOR and REMOTE_ADDR.
  • Otherwise, the client IP can be set using xdebug.remote_host, defaulting to localhost.
  • The client port is set using xdebug.remote_port, defaulting to 9000

DBGp proxy

There can be only a single xdebug.remote_host configured, so to support multiple clients (i.e. multiple developers) use xdebug.remote_connect_back to dynamically determine the debug client's address, except when using an unprotected server (that anyone can connect to).

In that case use a DBGp proxy, and let every debug client register with a unique identifier, the IDE key.

For example, the IDE key can be configured in PhpStorm using

Tools | DBGp proxy | Configuration

Fill in the IDE key, Host address of the DBGp proxy, and the Port for registration (default 9001).

Xdebug is then configured with the proxy address, typically on port 9000 and when starting a session the IDE Key is sent with the DBGp protocol message (the init element's idekey attribute).

The IDE key can be statically set using xdebug.idekey or defaults to environment setting DBGP_IDEKEY, USER, or USERNAME.

More likely, the IDE key is set dynamically, for instance using the XDEBUG_CONFIG environment variable (see below):

XDEBUG_CONFIG="idekey=session_name remote_host=localhost remote_port=9000"

Start remote debugging

If xdebug.remote_autostart is On, Xdebug will always attempt to connect to a debug client.

Otherwise, start a debug session manually.

CLI

When running PHP from the command line, set the XDEBUG_CONFIG environment variable to start a debugging session:

For instance

XDEBUG_CONFIG= php script.php

or, using the built-in web server

XDEBUG_CONFIG= php -S 0:8888 script.php

and trigger a debug session using

curl http://localhost:8888/

Its value can be empty, or it can be used to override the current settings in php-cli.ini.

XDEBUG_CONFIG="remote_host=localhost remote_port=9000" php script.php

HTTP client

When running a PHP script from an HTTP client, use one of the following methods to start a debugging session:

Several browser plugins exist that set the XDEBUG_SESSION cookie for you.

Once a debug session is started, Xdebug emits a cookie with the name "XDEBUG_SESSION" and as value the value of the XDEBUG_SESSION_START URL parameter.

XDEBUG_SESSION_STOP will stop the debug session by destroying the cookie.

xdebug.remote_cookie_expire_time specifies the timeout on the debug session cookie (default 3600 seconds).

See also

Clone this wiki locally