Using PhpStorm 8 for WordPress Debugging & Development

PhpStorm 8 is a cross-platform, IDE (Integrated Development Environment) that delivers a feature packed, fast, and efficient user interface for debugging and code editing. As a commercial product, you will find the runtime to be fast and what you would expect from a well written native application. While still requiring a Java runtime, PhpStorm feels much faster than eclipse or even the lighter weight Netbeans IDE. Like Netbeans, it works with either DesktopServer Limited or DesktopServer Premium editions. It also provides all the common editing features you would expect to find in a professional IDE: code folding, code completion, debugging with breakpoints and step functions, variable watch lists and inspectors, and multiple disciplines for syntax highlighting (JavaScript, HTML, PHP, etc. with an emphasis on PHP). Since WordPress ‘template tags’ are just PHP functions, PhpStorm can make working with WordPress fast and efficient. Now PHPStorm features WordPress specific settings for code styling and an intelligent WordPress API for autocomplete while coding. However, setup is still a challenge as the new version 8 user interface can be misleading and is broken in a key area. But we have a workaround! Don’t let the “nuance” (bug) detour you as PhpStorm is fully functional, albeit in need of a few workarounds. In this post, I will help you simplify the initial setup process of using PhpStorm with DesktopServer to give you a fast and professional IDE for WordPress development. Once acclimated, users will find version 8 debugging quick, robust and more responsive than ever.

Getting Started

If you haven’t already installed PhpStorm, you can find a free, fully functional 30 day trial for either Macintosh or Windows from their website at The installer is typical and straight forward. Simply install using the defaults. To work with DesktopServer, make sure you have checked the ‘Enable debug services’ check box in DesktopServer. You can find this setting in DesktopServer’s first main menu option ‘Stop or restart…’. Be sure to select the ‘Restart’ option followed by clicking the ‘Next’ button.

Create New Project from Existing Files

If you haven’t already created a DesktopServer website, take a moment to try the simple website as outlined in “Getting Started with DesktopServer”, steps 1 to 10. Adding your existing website to PhpStorm requires a few extra steps. The newest version of PhpStorm has a bug that prevents you from creating a website with existing source on startup (the option is disabled). It will enable if you create or open an existing project and close it immediately. But avoid this faux pas altogether and save time by just selecting the first enabled option to “Create a New Project”. We can specify our existing source files anyway.

Use the “…” button to bring up a folder selection dialog box. Navigate to your project’s site root folder. I.e. example, if your website is, the site root folder would be called and exist in your Documents/Websites folder. Select the “” folder and be sure to set the Project type to “Empty project”.

We’ll work around PhpStorm’s broken user interface that prevents us from selecting the “…existing files” option. After providing the path to your files, PhpStorm 8 will sense that you have existing source code files at the given location. Be sure to click the “Yes” button to keep your project’s files. PhpStorm will then start indexing all the existing project files and a progress bar will appear in the status bar at the bottom of the editor. Be sure to be patient and let this process complete as it is necessary to leverage PhpStorm’s useful code navigation and syntax checking features.

You will see a few prompts in the status bar after PhpStorm completes indexing. Click on the status bar to bring up the prompts for WordPress support and code styling. Enabling these features should autocomplete features when coding for the WordPress API as well as code indentation and styling that matches common WordPress’ coding standards.

Now you will need to create a PHP Web Application configuration. Start by clicking the drop down arrow in the upper right hand corner of the application and select the drop down menu for “Edit Configurations”. A dialog will appear titled “Run/Debug Configuration”. Click the plus symbol in the upper left corner of the dialog and select “PHP Web Application” from the drop down list of options.

Next, define the server configuration. Type the a name (we’d suggest this match your DesktopServer project’s domain, i.e. Click the checkbox “Single Instance Only”, followed by clicking the “…” button next to the “Server” field to define a server. A dialog box (titled “Servers”) will appear allowing you to define a new development server. Click the “+” button in the upper left corner of the “Servers” dialog box. You can specify a server and hostname (i.e. The hostname must match your DesktopServer domain name (i.e. Lastly, click the “OK” button to close the dialog box. Ensure the “Run/Debug Configuration” window has the “Server” field set and click “OK” to close the “Run/Debug Configuration” window.

Debugging WordPress in PhpStorm

PhpStorm 8′s debugging feature is somewhat more intuitive than in prior configurations. This setup doesn’t need the nonsensical, two-steps, “listening” button; you can just click the “debug” button to begin debugging. However by default, PhpStorm will stall at the first line of code within the site’s root index.php. Program execution always starts with index.php in the site root, but constantly opening that file and pausing there can quickly become annoying. We would suggest changing the default setting on startup to be even less cumbersome with less steps and clicks to start debugging your code.

Start by navigating to the Preferences (Macintosh) or Settings (Windows) dialog window. On Macintosh, this will be under the application pull down menu for PhpStorm -> Preferences. On Microsoft Windows, the pull down menu for File -> Settings. Navigate PhpStorm’s massively extensive tree menu on the left side to the location for Language and Frameworks -> PHP -> Debug. Uncheck the options for “Force break at the first line when no path mapping is specified” as well as the option for “Force break at the first line when a script is outside the project”. Click the “OK” button to dismiss the Preferences/Settings window. You can now start debugging your projects faster when setting custom break points to find bugs or check program flow. Please see the following paragraphs (below) for debugging examples.

What’s a Breakpoint?

A breakpoint is an intentional stopping or pausing of program execution put in place by the programmer for the purpose of debugging. As a web developer, you can pause execution of your WordPress application before it is completely transmitted to the web browser for display. Breakpoints can only be created in PhpStorm within source code files (.php files) on lines that contain PHP code. A computer programmer may wish to do this to suspend program flow and check on variables before, after, or during the program’s flow. Watching the program flow can also be accomplished to better understand how the program branches off between source code files, within plugins, themes, or to detect possible errors within any of the aforementioned files that may be causing unintended results.

Creating a Breakpoint

To set a breakpoint, click in the margin just left of the line of code you wish to pause execution on. In our example, we first open the index.php file from the site root of our development project (see step 1 – Open the index file). Next, we place a breakpoint on the line that reads require( dirname( __FILE__ ) . '/wp-blog-header.php' ); (see step 2 – Click the margin to set a breakpoint). When a breakpoint is set, the entire line will highlight in read. To begin the debugging process, click the toolbar icon that resembles a bug (see step 3 – Click the debug icon to start debugging). When a breakpoint is encountered during program execution, the red line of the breakpoint will transform and highlight in blue indicating that the instruction pointer is paused on the breakpoint line. Lastly, you may use the icons to control the program flow (see step 4 – Use the toolbar buttons to control program flow…). While a breakpoint is paused, you will note that the browser will be “stuck” waiting for the page to complete loading. The green arrow will resume program execution and send the content to the browser window. In contrast, the red square stop icon will end the debug process and abort sending the page to the web browser (which will immediately timeout). In addition to the left side vertical buttons, you will see the “step” buttons laid out horizontally. These buttons allow you to move one line at a time through the program execution.

Navigating Code and Breakpoints

When stopped at a breakpoint, you can advance one line at a time using the step buttons to execute a line of PHP code sequentially one line (aka “step”) at a time. If you encounter a PHP defined function, you may use the “Step Into” button to automatically open the file where the function is defined and step through the lines of PHP code that exists to define the function (see 1, Use “Step Into” button…). Even when not running in debug mode, PhpStorm 8 makes navigating code easy; PHP functions can be right-clicked (Cntrl+Click on Macintosh) to bring up a popup context menu to automatically go to the source code that defines the given function. PhpStorm will automatically move the cursor to the function declaration and open the associated source code file if it is not already open (see 2, Right-click a PHP function and select Go To -> Declaration). For example, we have opened the index.php file for the current theme. You can find this file for the Twenty Fourteen theme in the theme’s subfolder. I.e. at /wp-content/themes/twentyfourteen/index.php. Place the cursor within the function has_posts() and right-click the function. Follow the popup menu for Go To -> Declaration. PhpStorm will automatically locate and open the query.php file where the function is declared and place the cursor at the precise location of the function definition.

Now that you are armed with the knowledge of how to set breakpoints and navigate WordPress’ PHP code, you will have the ability to watch how WordPress and it’s plethora of available plugins work. Reading code with the debugger can help you understand exactly which lines get execute and when. Peeking into the contents of variables will assist you in tracking down logic errors and gain a better understanding of how the code works.

Last Notes

Despite the initial, less than intuitive project setup process, PhpStorm 8 appears to be loaded with features that cater and lends itself specifically to WordPress developers. Functionality is definitely a major improvement with excellent debugging integration such as floating variable hints and WordPress autocomplete coding capabilities. The variable watch window and code inspectors appear to be more consistent than competing products and stepping through code is quick and easy. PhpStorm 8 matches Netbeans on a feature by feature basis but operates considerably faster. There are a few menu items that overburden the appearance of the user interface and many old features that are of little use. However, part of PhpStorm’s cross platform success is merely it’s existence; it’s certainly better to have robust set of tacked on features (even if seldom used) than to not have them at all. Give it try; it might just be the productivity boost you’ve been looking for in a dedicated PHP editor.