This tutorial describes how to get started with PHP web application debugging in PhpStorm IDE using Xdebug.

1. Install Xdebug

In order to use Xdebug with PhpStorm for debugging PHP applications you should have PHP development environment configured with Xdebug extension installed and this task is beyond PhpStorm’s control. More information on configuring PHP development environment can be found at our webhelp

Make sure that you have Xdebug installed properly. Please note that Xdebug version should fit PHP interpreter version you have (mind the PHP version number and thread-safe/non-thread-safe option) and installed as zend_extension. Don’t forget to set the xdebug.remote_enable setting to 1 in php.ini file. Information about Xdebug installation and configuration can be found here. You can download the latest version of Xdebug plugin at the official web site. Recommended stable versions are 2.2.1 or 2.1.3.

You can check the configuration executing php --version in the terminal

or execute page with phpinfo(); php function and check that you have Xdebug extension enabled - xdebug section of the document with installed version should be available.

2. Prepare PhpStorm

Toggle the “Listen debugger connections” button. Don’t use any run configurations.

3. Set a breakpoint in the source code

Apart from setting breakpoint manually you can use an option Run | Break at first line in PHP scripts in order to have an automatic breakpoint at first line of every PHP script you debug.

4. Activate debugger on server

In order to activate debugger you need to set special GET/POST or COOKIE parameter (more details). You can do it manually, but it is much more convenient to use one of the special tools such as browser toolbars or bookmarklets for that.

Try our PhpStorm bookmarklets generator and get bookmarklets which will work in any modern browser and allow you to start/stop a debugging session by controlling the Xdebug cookie.

Names of menus and options can vary - depends on you internet browser. We’ve used Firefox for this section.

4.1. Make Bookmarks Toolbar enabled (View | Toolbars | Bookmarks Toolbar)

4.2. Open address

4.3. Click Generate button under Xdebug section, drag-and-drop links “Start debugger” and “Stop debugger” from appeared Debug section to Bookmarks Toolbar.

5. Start a debug session in browser

6. Reload the current page

7. Set initial path mappings

Switch to PhpStorm and set the initial path mappings by selecting the path to the local copy of the script that we are debugging. These paths are similar if you are editing files directly on the server. The “Incoming Connection” dialog should appear automatically.

8. Debug!

On reaching the breakpoint the debugger suspends. Now let’s investigate the application.


In some cases you may get an error message “Remote file path ‘path/to/script/on/the/server.php’ is not mapped to any file path in project“ or “The script ‘path/to/script/on/the/server.php’ is outside the project”. This means that PhpStorm does not know which local file corresponds to the specified remote file path.

You can solve this problem quickly. Just set up necessary path mappings clicking the relevant link.