Step‑by‑Step Guide to Debug PHP with Xdebug in PhpStorm

Installation and configuration of Xdebug

Prerequisites

{PHP_INSTALL_DIR} – absolute path of the PHP installation directory.

{EXTENSION_NAME} – name of the extension to install.

Command‑line tools such as php -v, php, and phpize assume the PHP bin directory is in $PATH. Add it to the system environment if necessary.

Windows

Download the DLL that matches your PHP version, architecture (32‑bit or 64‑bit), VC runtime, and thread‑safety (TS or NTS) from https://xdebug.org/download.php. Use phpinfo() to determine the required build (e.g., "PHP 7.0 VC14 (32 bit)").

[XDebug]
zend_extension = "C:\\path\\to\\xdebug.dll"

Linux

wget -c https://xdebug.org/files/xdebug-2.5.5.tgz
tar xvzf xdebug-2.5.5.tgz
cd xdebug-2.5.5
phpize
./configure --with-php-config={PHP_INSTALL_DIR}/bin/php-config
make && make install

macOS

brew install php71-xdebug

Common Xdebug configuration

Edit

php.ini</p> and replace any existing Xdebug section with the following (adjust paths as needed):</p>
<pre><code>[xdebug]
zend_extension="/usr/local/opt/php71-xdebug/xdebug.so"
xdebug.remote_enable=1
xdebug.idekey="PHPSTORM"
xdebug.remote_host=localhost
xdebug.remote_port=9008

Set zend_extension to the actual path of the Xdebug shared object or DLL. xdebug.remote_host should be localhost for local development; use the host IP (e.g., 192.168.33.1) for remote Vagrant or VM setups. xdebug.remote_port must match the port PhpStorm will listen on (default 9008 in this guide).

After saving php.ini, restart the PHP service or web server.

PhpStorm configuration

Open Preferences → Languages & Frameworks → PHP → Debug and set the Debug port to 9008 , matching xdebug.remote_port . Configure a deployment server for the project: Create a server named “demo” with type “in place”. Set the “Web server root URL” to http://demo.dev . Validate the setup via Run → Web Server Debug Validation → Remote Web Server → Validate . Successful validation confirms Xdebug can connect.

Browser integration

Install the “Xdebug helper” extension for Chrome. In the extension options set the IDE key to PHPSTORM and save.

Starting a debugging session

In PhpStorm click the telephone‑icon in the top‑right to enable listening for debug connections (icon turns green). Set breakpoints in your PHP source files, open http://demo.dev/ in Chrome, and activate the Xdebug helper “Debug” button (button turns green). The browser request will pause at the defined breakpoints inside PhpStorm, allowing step‑through, variable inspection, and normal debugging workflow.