Why step-through debugging changes everything. Most developers underestimate the power of seeing code execute in real time. It’s not just “nice to have”. It’s the fastest path from “something’s broken” to “I know exactly why.” With the right tools, you can pause your app mid-execution, inspect variables, evaluate expressions, step through functions, and watch the call stack unfold. Bugs stop being mysterious; they become apparent.
If you’ve used Java or .NET, this will feel like home: breakpoints, stepping into/
What you’ll get from this series: This guide shows you how to set up debugging in PhpStorm for a WordPress site running locally via PhpStorm’s built-in web server. You’ll go from “logs and guesswork” to “pause, inspect, fix” in minutes.
Highlights you’ll use
- Breakpoints: Stop execution at critical lines (plugins, themes, hooks, AJAX handlers, REST endpoints).
- Step-through control: Step into functions, step over lines, step out of call chains and no print_r required.
- Watches and evaluation: Pin variables to watch their values change and run expressions on the spot.
- Call stack clarity: See exactly how you got to the current line (filters, actions, includes).
- Path mapping confidence: Know the server is hitting the same files you’re editing.
- Zero-surprise debugging: Catch malformed JSON, unexpected redirects, and non-200 responses immediately.
How it works (mental model)
- Xdebug is a PHP extension that “phones home” to your IDE when a request runs.
- PhpStorm listens on a port (typically 9003) and establishes a debugging session.
- When a breakpoint is hit, execution pauses; you get full visibility and control.
- This works for browser requests, CLI, AJAX, and REST, pretty much any PHP that runs.
What’s in this guide
- Set up PhpStorm to listen for Xdebug.
- Configure Xdebug to auto-start debugging for local requests.
- Run WordPress inside PhpStorm’s built-in web server.
- Verify everything: hit a breakpoint, inspect the call stack, and step through code.
- Avoid the classic pitfalls (wrong PHP binary, wrong port, missing path mappings, corrupted output).
What’s coming next (if you’re interested)
- Eclipse (PHP/
Java): Debugging setups and workflows. - NGINX remote servers: Using .user.
ini for per-directory Xdebug config. - Apache remote servers: Using .htaccess correctly for Xdebug and environment parity.
Yes, you can debug a remote/
Bottom line: Turning on interactive debugging isn’t just a setup chore. It’s a superpower. It transforms how you reason about your application, reduces fix time dramatically, and gives you certainty. Once you try it, you won’t want to go back.
This article runs through the process required to get the PHPStorm built-in webserver to run correctly and for it to use Xdebug to assist in debugging problems in code.
PHP Installation
You will need to install PHP on your system, either Windows or Mac (Linux).
In Windows, you can get prebuilt binaries from https://windows.php.net/ – most come with a reasonably complete extension set, of which you will need to configure (uncomment) within the php.ini that is supplied with it. There are some extensions, such as Oracle, where you may need to do further research. You will need to make sure you have Xdebug.
For Mac – If ‘Homebrew’ is installed, it can help you install PHP as there is a package for it. See https://formulae.brew.sh/formula/php@8.2 – Ensure you follow the instructions clearly – you will need to modify your ‘PATH’ to access the PHP binary. Again, you will need to install Xdebug.
Verify PHP Installation
To check you have the required libraries, run:
php -mYou will expect to see Xdebug at the bottom of the list. You should also find items such as
- mysqli
- pdo_mysql
- SimpleXML
- json
- soap
- curl
Once you have gotten this far, you will need to modify your ‘php.ini’ file to ensure that XDebug will initiate a request when you view a page via your local web server. At the bottom of your ‘php.ini’ file, put:
[xdebug]
xdebug.mode=develop,debug
zend_extension = xdebug
xdebug.start_with_request = yes
xdebug.client_host = 192.168.1.50
xdebug.client_port = 9003
xdebug.log_level = 0
xdebug.idekey='PHPSTORM';
Make sure it is the only Xdebug node or you will experience issues.
PHPStorm Setup
Before setting up the Web server, ensure your PHP Installation is correctly configured. Note: These instructions may differ slightly in the Mac variant.
PHP Interpreter Configuration
Go to File → Settings (or Ctrl-Alt-S in Windows)
Select ‘PHP’ and you will see the CLI Interpreter section (which may or may not be blank).
Click the ‘…’ icon on the right and navigate to your PHP installation.
Make sure you verify the PHP configuration file referred to here is the same one you just added Xdebug configuration to!
Web Server Configuration
PHP Storm needs to be set up to run your web server and point it to your code base.
For a ‘WordPress’ installation, it relies on redirections from any given path to the main ‘index.php’ file. This is achieved within the PHPStorm installation by the use of a ‘router’ script.
The router script is where requests are sent first to ensure they are sent to the appropriate place.
On a traditional web server, this would be performed using a ‘.htaccess’ file in Apache, or a ‘.user.ini’ file in NGinx.
Use the ellipsis icon in the top right of the PHP Storm IDE to enter the debugging configuration area.
Within this configuration panel, you will see the ‘+’ icon.
Navigate down to ‘PHP Built-In Web Server’ and select it. This will open the dialogue that allows us to teach PHPStorm where to run your code.
You can set up as many servers as you would like, especially if you are running multiple projects. By simply using a different port, they can all run independently from one another.
This ‘Run/Debug Configuration’ panel allows you to run any number of scripts or tests, so do become familiar with it. When testing command-line scripts, for example, it’s very common to use the ‘PHP Script’ test.
When coming to the PHP tests with Xdebug, being able to see what is going on at the time of execution will improve your bug resolution process a heap.
Within the web server configuration, only a handful of items require values.
- Name – Vanity name for the server
- Host – How the server is accessed
- Port – Which port the request will come in on.
- The document root – the base path to the web application.
- The router script – as mentioned earlier, it routes all requests to a single entry point.
When working with others in a development environment where the configuration of the application indicates what the expected ‘URL’ is (WordPress, for example, stores the hostname of the site in its ‘wp_options’ table), all developers should use these same port so that the URLs generated for the application that read this table are created in a way that your setup works with.
Ensure Debugging Requests are captured.
When a request is forwarded via XDebug, it needs to be mapped from the remote code that the server can see, and where that exists on your file system. That’s how the two are paired, so you can step through code.
By default, PHP Storm will ignore connections that it does not know to reduce noise. This setting is excellent to keep enabled after you have your mapping correct. It is located under PHP → Debug.
When setting this up for the first time, disable this setting, so the new request coming from your local web server can be caught and you can configure the appropriate mappings.
Mapping configuration is located under PHP → Servers.
When this is complete, you can re-check ‘ignore’ to prevent random requests from interrupting your work.
Remember this flag! Many developers have been caught trying to figure out why debugging is not working; when it is, it’s just ignored.
WordPress Setup
As mentioned earlier in the document, WordPress generates the URLs used throughout the platform by using the wp_options setting (generally settings 2 and 3, if I recall correctly).
When creating a staging or test environment, ensure it is updated to navigate the application cleanly. You will only forget this once! 
Testing and use
To test everything is working together, create a ‘test.php’ file in the wp-admin directory. Simply put:
echo 'test';
In the file and click on the line number to set a ‘break point’.
Start your web server and ensure connections are listening for the debugger.
The ‘Play’ starts the web server. The ‘bug’ with the ‘cross’ or ‘beam’ indicates whether it is active or not.
Navigate to your test page: https://localhost:8888/wp-admin/test.php in this instance:
Before the ‘test’ is executed on the screen, you will notice that PHPStorm signals attention and the ‘echo’ in your script is highlighted.
Debugging steps are managed from the ‘Debug’ panel, which should have automatically opened as soon as the breakpoint was hit. There are tutorials on the internet on how this panel works, but fundamentally, you will be looking for
Play – continue executing until finished or we hit the next break point.
Step In – Move inside the method being called
Step Over – Move over the method being called
Step Out – Move out of the method being called
Stop – Abort the request entirely (the web page you have called will not complete rendering – useful if the process you are testing would damage data if the request were permitted to continue).
Once you understand how to control debugging steps within your script, you can place breakpoints anywhere in your test to see exactly what is happening.
The real game changer is being able to see what variables are set and what they are set to at the time! You will notice the ‘Threads and Variables’ section, which shows you precisely what is active.
Hopefully, this guide assists you in debugging your application and accelerates your development!