Configure PHP Remote Debugging in Vagrant box with Xdebug and PhpStorm

Configure PHP Remote Debugging in Vagrant box with Xdebug and PhpStorm

Debugging PHP applications in a Vagrant box can be challenging without the right setup. In this guide, we’ll walk through configuring PHP remote debugging using Xdebug and PhpStorm inside a Vagrant environment. By setting up proper configurations, you can seamlessly debug your PHP code, set breakpoints, and inspect variables in real-time, improving your development workflow.

Note: This article concerns PHP 7.0,PhpStorm 2017.2 (EAP) and Vagrant box bento/centos-7.2.

Step1: Install Xdebug on your Vagrant virtual machine

You need to have Xdebug installed on your virtual machine to benefit from its services.

sudo yum install php-xdebug

Then, we need configure it:

We need enable the remote debug and add IDEKEY on XDEBUG. To do that, we need modify the php-xdebug configuration file (xdebug.ini).

Lets modify the php-xdebug configuration file

vi /etc/php.d/15-xdebug.ini

And the following lines at the end of the file

xdebug.remote_enable=true
xdebug.remote_connect_back=true
; add your idekey here. My key is : IYNGARAN_XDEBUG_KEY
xdebug.idekey=IYNGARAN_XDEBUG_KEY

Then restart your web server.

Step2: Configure PhpStorm

Now we need to configure PhpStorm.

  1. First, select the “Edit configurations” item in the “Run” menu.

  2. Then, add a new “PHP Remote Debug” configuration. From here, when you click on the “PHP Remote Debug”, You will get the following window.

  3. Here, we need to add name for this configuration. So, I am going to use my virtual host name – iyngaran.samples.dev as name and we need to add server. To add new server, click on the icon next to the Servers dropdown. You will get the following window.

  4. Click on the + icon to add new server.

  5. Here, we need to add the name, host, port and we need to select xdebug as Debugger. And then click on the check box – “Use path mappings (Select if the server is remote or symlinks are used)”.

  6. In that, You need to set the local File/Directory path and Absolute path on the server.

  7. My Absolute path on the vagrant server is /home/vagrant/learning.portal/apps/samples.dev/public_html/src/web/. So I add this to absolute path on the server and then click Apply and OK. You will get the following window, when you click on OK.

  8. Here, we need to add Ide key. My IDE key is : IYNGARAN_XDEBUG_KEY (It is in the /etc/php.d/15-xdebug.ini)

    Then click on apply and OK.

    Now that Vagrant with Xdebug is up and running, let’s configure Xdebug Chrome extension.

Step3: Install and Enable Xdebug extension to your web browser (Chrome)

  1. First, we need to install it from Chrome Web Store – https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc?hl=en

  2. Make sure that the extension is enabled on your browser’s extensions list page – chrome://extensions/.

  3. Now, you should see on the right side of the address bar the extension’s symbol. Now, Our browser also ready with the xDebug extension.

Step4: Lets debug a script.

  1. Enable debugging on your browser – in your browser click on the bug in your address bar to switch to the “Debug” mode.

  2. Add your breakpoints by clicking to the left of the lines

  3. Then on PhpStorm, Start listening for PHP Debug connections.

  4. Then run the script from browser – http://iyngaran.samples.dev/test.php

    Now, here you can see the debugging is working.

  5. Click ‘Step Over (F8)’

I hope you find this tutorial useful! 😀