If you are using Docker Machine and VirtualBox, use the IP of the VirtualBox network interface. Here is an example how to override the default Xdebug remotehost option. $ docker run -rm -it -volume $(pwd):/app -e PHPIDECONFIG='serverName=application' prooph/php:7.1-cli-xdebug php -d xdebug.remotehost=172.17.0.1 your PHP file Other PHP. XDebug PHP CLI Applications in Eclipse I have some phpunit test cases which I need to debug in my eclipse. I’m trying to explain the debugging setup in the following situation. Docker-php-cli: # define the directory where the build should happened, # i.e. Where the Dockerfile of the service is located # all paths are relative to the location of docker-compose.yml build: context:./php-cli # make the SSH port available via port mapping ports: - '2222:22' # reserve a tty - otherwise the container shuts down immediately. Finally, set `phpxdebugdefaultenable` to `1` and `phpxdebugclidisable` to `no`. These last two settings are very important for being able to debug Drush commands. Then, open a terminal and change directory to where the DrupalVM files are located. Keep the terminal open are going to execute various commands from there.
Install the extension: Press
ext install php-debug.
This extension is a debug adapter between VS Code and Xdebug by Derick Rethans. Xdebug is a PHP extension (a
.so file on Linux and a
.dll on Windows) that needs to be installed on your server.
Install XdebugI highly recommend you make a simple
test.phpfile, put a
phpinfo();statement in there, then copy the output and paste it into the Xdebug installation wizard. It will analyze it and give you tailored installation instructions for your environment. In short:
- On Windows: Download the appropriate precompiled DLL for your PHP version, architecture (64/32 Bit), thread safety (TS/NTS) and Visual Studio compiler version and place it in your PHP extension folder.
- On Linux: Either download the source code as a tarball or clone it with git, then compile it.
Configure PHP to use Xdebug by adding
zend_extension=path/to/xdebugto your php.ini. The path of your php.ini is shown in your
phpinfo()output under 'Loaded Configuration File'.
Enable remote debugging in your
For Xdebug v3.x.x:
For Xdebug v2.x.x:
There are other ways to tell Xdebug to connect to a remote debugger, like cookies, query parameters or browser extensions. I recommend
start_with_request(Xdebug v3) because it 'just works'. There are also a variety of other options, like the port, please see the Xdebug documentation on remote debugging for more information. Please note that the default Xdebug port changed between Xdebug v2 to v3 from 9000 to 9003. The extension still defaults to 9000, so make sure your configuration in
If you are doing web development, don't forget to restart your webserver to reload the settings.
Verify your installation by checking your
phpinfo()output for an Xdebug section.
VS Code Configuration
In your project, go to the debugger and hit the little gear icon and choose PHP. A new launch configuration will be created for you with two configurations:
- Listen for XdebugThis setting will simply start listening on the specified port (by default 9000) for Xdebug. If you configured Xdebug like recommended above, everytime you make a request with a browser to your webserver or launch a CLI script Xdebug will connect and you can stop on breakpoints, exceptions etc.
- Launch currently open scriptThis setting is an example of CLI debugging. It will launch the currently opened script as a CLI, show all stdout/stderr output in the debug console and end the debug session once the script exits.
Supported launch.json settings:
hostname: The address to bind to when listening for Xdebug (default: all IPv6 connections if available, else all IPv4 connections)
port: The port on which to listen for Xdebug (default:
stopOnEntry: Whether to break at the beginning of the script (default:
pathMappings: A list of server paths mapping to the local source paths on your machine, see 'Remote Host Debugging' below
log: Whether to log all communication between VS Code and the adapter to the debug console. See Troubleshooting further down.
ignore: An optional array of glob patterns that errors should be ignored from (for example
xdebugSettings: Allows you to override Xdebug's remote debugging settings to fine tuning Xdebug to your needs. For example, you can play with
max_depthto change the max number of array and object children that are retrieved and the max depth in structures like arrays and objects. This can speed up the debugger on slow machines.For a full list of feature names that can be set please refer to the Xdebug documentation.
max_children: max number of array or object children to initially retrieve
max_data: max amount of variable data to initially retrieve.
max_depth: maximum depth that the debugger engine may return when sending arrays, hashs or object structures to the IDE.
show_hidden: This feature can get set by the IDE if it wants to have more detailed internal information on properties (eg. private members of classes, etc.) Zero means that hidden members are not shown to the IDE.
Options specific to CLI debugging:
program: Path to the script that should be launched
args: Arguments passed to the script
cwd: The current working directory to use when launching the script
runtimeExecutable: Path to the PHP binary used for launching the script. By default the one on the PATH.
runtimeArgs: Additional arguments to pass to the PHP binary
externalConsole: Launches the script in an external console window instead of the debug console (default:
env: Environment variables to pass to the script
- Line breakpoints
- Conditional breakpoints
- Function breakpoints
- Step over, step in, step out
- Break on entry
- Breaking on uncaught exceptions and errors / warnings / notices
- Multiple, parallel requests
- Stack traces, scope variables, superglobals, user defined constants
- Arrays & objects (including classname, private and static properties)
- Debug console
- Run as CLI
- Run without debugging
Remote Host Debugging
To debug a running application on a remote host, you need to tell Xdebug to connect to a different IP than
localhost. This can either be done by setting
xdebug.remote_host to your IP or by setting
xdebug.remote_connect_back = 1 to make Xdebug always connect back to the machine who did the web request. The latter is the only setting that supports multiple users debugging the same server and 'just works' for web projects. Again, please see the Xdebug documentation on the subject for more information.
To make VS Code map the files on the server to the right files on your local machine, you have to set the
pathMappings settings in your launch.json. Example:
Please also note that setting any of the CLI debugging options will not work with remote host debugging, because the script is always launched locally. If you want to debug a CLI script on a remote host, you need to launch it manually from the command line.
- Ask a question on StackOverflow
- If you think you found a bug, open an issue
- Make sure you have the latest version of this extension and Xdebug installed
- Try out a simple PHP file to recreate the issue, for example from the testproject
- In your php.ini, set
xdebug.remote_log = /path/to/logfile(make sure your webserver has write permissions to the file)
'log': truein your launch.json
To hack on this adapter, clone the repository and open it in VS Code. You need NodeJS with NPM installed. Install dependencies by running
You can debug the extension (run it in 'server mode') by selecting the 'Debug adapter' launch configuration and hitting
F5. Then, open a terminal inside the project, and open the included testproject with VS Code while specifying the current directory as
VS Code will open an 'Extension Development Host' with the debug adapter running. Open
.vscode/launch.json and uncomment the
debugServer configuration line. Hit
F5 to start a debugging session. Now you can debug the testproject like specified above and set breakpoints inside your first VS Code instance to step through the adapter code.
The extension is written in TypeScript. You can compile it through
npm run build.
npm run watch enables incremental compilation.
Tests are written with Mocha and can be run with
npm test. The tests are run in CI on Linux, macOS and Windows against multiple PHP and Xdebug versions.
I use Docker for development and for my website too. Now it's time to throw away
var_dump and to use Xdebug for PHP Docker container. It's quite easy, because I have created a several Docker PHP Xdebug Images on GitHub. You have only to set your path mappings in your IDE. This image can also be used to generate the code coverage with PHPUnit. Ok, let's go step by step.
Pull the PHP Xdebug image from Docker Hub
Ensure Docker is installed and then run the following command:
This can take some minutes. In the meantime, you can configure your IDE path mappings.
Configure path mappings in PhpStorm
Important is the server name application. PhpStorm uses the
serverName to determine the right server. xDebug is automatically enabled in the configuration. If you run this Docker container and listen to incoming connections, it stops on the activated breakpoints. Open the settings
File -> Settings -> Languages & Frameworks -> PHP -> Server and enable path mappings. Fill out the name with application and set /app to the absolute path mapping on the server of the root folder. Your project files will be mounted there.
Start the PHP Xdebug Docker container
You have configured your path mappings and enabled listen for incomming Xdebug connections, then you can start the container with the following command from the root of your project.
It's important that your path mapping has the name application and to pass the environment variable PHP_IDE_CONFIG with the name of the server. It is recommended to create a simple bash file which works with every project. Create a file
docker-xdebug.sh in your ~/bin folder and put the following lines to it.
Make this file executable with
chmmod +x ~/bin/docker-xdebug.sh and you can start a new Xdebug session with:
Breakpoints doesn't work?
Don't expose the Xdebug port 9000
At default, Xdebug's remote host is configured with
xdebug.remote_host=172.17.0.1, but it can be different to your Docker gateway IP address. To check your Docker gateway IP run the command
$ ifconfig and look for the docker0 network adapter. Since Docker 1.9, the Docker gateway IP for me is 172.17.0.1. You can override the default Xdebug configuration with the
php -d xdebug.remote_host=172.17.0.1 parameter. If you are using Docker Machine and VirtualBox, use the IP of the VirtualBox network interface. Here is an example how to override the default Xdebug remote_host option.
Other PHP Versions
The prooph Docker PHP build on Docker Hub includes several PHP versions from PHP 5.6 to 7.2 for CLI and PHP-FPM as well.
Clix Bugha Bizzle
Docker is a perfect match for PHP development. Note that these Xdebug settings also work with a web server like nginx and php-fpm. Interested in profiling? Read more about profiling.
Xdebug Cli Remote
Vagrant users can read Vagrant remote PHP & CLI debugging with PHPStorm.