Xdebug is an extension used for debugging PHP. One of the most popular IDEs, Visual Studio Code, can also benefit from Xdebug with
PHP Tools. There are several ways to install Xdebug, but the most secure one is to compile the source code which is compatible with the specifications of your computer.
In this article, you will find out how to compile the source code to install Xdebug for "
PHP Tools for VS Code" on macOS. We’ll assume that you have already installed PHP Tools for your macOS, but if you haven’t, you’ll find a tutorial right here.
As explained on their website, Xdebug extensions are released for the PHP versions at the time, so there are releases of Xdebug as PHP versions there are. Some of these versions may not be compatible with your software. To be sure which file you need to download, you can use Xdebug’s Wizard.
First, get your php information. Open a command prompt, and then write:
$ php –i
When your php information is displayed, select it all by pressing
Cmd+A and then
Cmd+C to copy it.
Then, open the wizard here. On the white input box, paste the php information and press the analyse my phpinfo () output button.
The wizard will display the recommended file to download and also some additional instructions.
Click on the download link on number 1 and save the source file.
The source file will be downloaded with the extension
tar. Before the installation, you need to unpack it or uncompress it/untar it. For unpacking, you can either use any application like Unarchiver or just use the command prompt.
To unpack the tar/tgz file by using the command prompt, first, change the directory where you downloaded the file. By default, it’s downloaded to the “
Downloads” folder. So, change the folder to “
Write the following command to untar the file. Be sure that the filename is exactly the same as the downloaded file.
$ tar -xzf xdebug-2.6.1.tgz
This command will unpack the source file to a folder with the same name.
First, change the directory to the folder which has just being unpacked from the source file. Then, run this in the command prompt:
$ cd xdebug-x.x.xxxx
phpize is not in your path, you should use /path/to/phpize.
If the phpize command works as expected, the result’s page must look like the picture below:
If there is an
autoconf error, you can install
autoconf with Homebrew and then export it.
$ /usr/bin/ruby -e "$(curl –fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew install autoconf
$ export PHP_AUTOCONF=/usr/local/bin/autoconf
In case of any missing x-code command line tools, run the following to install:
$ xcode-select --install
To configure the system for Xdebug, you need to get the build ready. Write in the command prompt:
$ ./configure —-enable-xdebug
In case of errors in parameters, just use the command, ./configure:
And if ./configure is not in your path, write:
$ ./configure --enable-xdebug --with-php-config=/path/to/php-config
Now, it’s time to finish the compilation of the source file. To build the software, just write:
If you see the sentence “Build complete” in the command prompt, it means that the compiled file “
xdebug.so” has been created in the “modules” directory.
Now that the software is built and ready to run, the compiled file can be copied to its final destination. The
make install command will copy the built program, its libraries and documentation to the correct locations.
It’s important that you note the location of the destination directory which is displayed in the results to include it in the
You can also prefer not to use
make install and copy the
Xdebug.so manually. Then, follow the next set of instructions.
First, create the destination directory. The destination folder is indicated in the Xdebug Wizard’s instructions page from step 1 (the red line on the picture below).
Run that command showed on number 8:
$ mkdir /usr/local/lib/php/pecl/xxxxxxxx
Then, copy “
xdebug.so” to the directory you just created.
$ cp modules/xdebug.so /usr/local/lib/php/pecl/xxxxxxxx
By now, the compilation of the file,
xdebug.so, is completed. But you still need to introduce this file in your
First, you need to locate your
php.ini file then edit it.
To find out the location of your
php.ini file, the quickest way is to look it up in the php information which is displayed in the command prompt, like we did on step 1 of this tutorial. Open a command prompt and write:
$ php –i
You will find the exact location of your
php.ini file in the “
Loaded Configuration File” section. Select the path of your
php.ini file and copy it.
To edit the
php.ini file, you can use any text editor. For example, in the command prompt you could use the Nano editor to edit the file as shown below.
However, this editor can be confusing and sometimes it’s challenging to use. We recommend to use Visual Studio Code (VS Code). To edit your php.ini in VS Code, write:
If you don’t see the word “code” in your path, you need to add it. Open VS Code, click View/Command Palette menu and select “Shell Command: Install ‘code’ command in PATH” as shown below:
After you opened the php.ini file in VS Code, add the following lines in it. Note that the file path will be the exact location in which you copied xdebug.so file.
Xdebug.remote_enable = 1;
Xdebug.remote_autostart = 1;
After completing all previous steps, make sure that
Xdebug support is enabled and write the following code to see if the installation was successful.
$ php –i | grep xdebug
You have completed the Xdebug installation with its full configuration. Now, you can begin debugging your code.