Use Xdebug for PHP

Using Xdebug for PHP allows developers to debug PHP-processes by connecting interactively. This allows setting breakpoints, changing content and reviewing stack traces.

We support the usage of xdebug by installing and configuring the required packages on the application instances that use PHP. To allow remote debugging we install an Xdebug proxy on the BastionHost of your environment.

To enable Xdebug for PHP please contact our root360 customer service.


Preconditions

Xdebug Usage

When Xdebug is activated, you can connect to your Xdebug sessions by following these steps:

  1. On your bastion host, start the program xdebug-helper. This will start an xdebug proxy in the background and print out connection information.

  2. Run the printed SSH-command on your local workstation in another shell.

  3. Connect your Xdebug client to the debugger:

    • debug-proxy: localhost:9001

    • client-listen-port: use the randomly chosen port printed by xdebug-helper

    • IDE-Key: use one of the keys printed by xdebug-helper. Every role gets its own IDE-Key to allow full control of the debugging process.

 

Simple example with one role

On bastion host (example output)

$ xdebug-helper Starting xdebug proxy session (lasts 24h) ... Access logs by running 'screen -r xdebug-proxy' (leave with <ctrl>+<a>+<d>) Client-Listen-Port: 20184 Debug-Proxy: localhost:9003 SSH-Command: ssh -A -R 20184:localhost:20184 -L 9001:localhost:9001 <bastion-host> Available IDE-Keys: <ide-key-role1>, <ide-key-role2> $

On local workstation (example output)

  1. Connect using SSH, specifying client-listen-ports

    $ ssh -A -R <client-listen-port>:localhost:<client-listen-port> -L 9001:localhost:9001 <bastion-host>
  2. In another set of shells you can use dbgpClient to debug each role:

    $ curl -LO https://xdebug.org/files/binaries/dbgpClient $ chmod +x dbgpClient # register client with first role $ ./dbgpClient -f -r '<ide-key-role>' -y localhost:9003 -p <client-listen-port> proxyinit | success Xdebug Simple DBGp client (0.2)Copyright 2019-2020 by Derick Rethans Waiting for debug server to connect on port 20184.

Now you can start debugging (see Help for commands).

When your debugging session is done (exit the client using Ctrl +C), you need to de-register the IDE-key from the proxy for future usage. Otherwise, it will remain blocked:

Advanced Example with two roles

On bastion host (example output)

On local workstation (example output)

  1. Connect using SSH specifying two client-listen-ports (you can choose any port you like, e.g. 20184 and 20185 in this example):

  2. In another set of shells, you can use dbgpClient to debug each role:

    • connect to role backend:

    • connect to role frontend:

Now you can start debugging (see Help for commands). When your debugging session is done (exit the client using Ctrl +C), you need to deregister the IDE-key from the proxy for future usage. Otherwise, it will be blocked.

 

Tools

Browser Extensions

 

Screencast using PhpStorm (Simple Example)

We have prepared a PhpStorm screencast illustrating how to set up xdebug (download).

Related tutorials

Related components

 


root360 Knowledge Base - This portal is hosted by Atlassian (atlassian.com | Privacy Policy)