Using PhpStorm For WordPress Debugging & Development

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  http://www.jetbrains.com/phpstorm/. The installer is typical and straightforward. Simply install using the defaults. To work with DesktopServer, make sure you have checked the ‘Debug and Trace’ 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 www.example.dev.cc website as outlined in  “Getting Started with DesktopServer”, steps 1 to 10. Adding your existing website to PhpStorm requires a few extra steps. From PhpStorm’s main dialog, select the option to “Create New Project from Existing Files”.

DesktopServer will personalize your website project with its own isolated, unique domain name in addition to its own document root. Therefore, when PhpStorm prompts you to “Choose Your Scenario”, simply select the first option titled, “Web server is installed locally, source files are located under its document root”.

PhpStorm will then prompt you to “Choose Project Directory”. This will be your website’s root folder. By default, DesktopServer creates your site root as a folder with the same name as your website’s domain name and as a sub-folder at ./Documents/Websites. Select the folder and click the “Next” button to continue. For our www.example.dev.cc website, we’ve selected the ./Documents/Websites/www.example.dev.cc folder.

Next, PhpStorm will ask you to “Add Local Server”. You will want to fill out the name field (we use the website’s domain), i.e. www.example.dev.cc. Then fill out the personalized “Web server root URL” field as it was created in DesktopServer, i.e. http://www.example.dev.cc. Note that DesktopServer distinguishes between a www and no-www websites. Make sure that the URL matches that domain name you created in DesktopServer. Click the “Next” button to continue.

Click Next and PhpStorm may show an Untrusted Service’s Certificate dialogue. Click accept to continue. PhpStorm will then prompt you to “Specify a Web Path”. Leave this field blank, Click the “Finish” button.

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.

Next, we need to review and modify the PHP configuration to work with DesktopServer and your WordPress development website. To do this, go to File > Settings > Languages and Frameworks > PHP. Be sure to modify the include path(s) to match your platform.

If you are on Windows, make sure that the include path C:\xampplite\php is present. If you are on Macintosh, ensure that the path to /Applications/XAMPP/xamppfiles/lib/php and /Applications/XAMPP/xamppfiles/etc is present.

Now you will need to create a PHP Web Application configuration. Start by clicking Run > Edit Configurations then click the plus symbol in the upper left corner of the dialog and select “PHP Web Page 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. www.example.dev.cc). 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. www.example.dev.cc). The hostname must match your DesktopServer domain name (i.e. www.example.dev.cc). 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′s debugging feature is somewhat more intuitive than in prior configurations. 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 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.

While PhpStorm has a start (green ‘play’ icon) button for console and linear web applications, it is awkward when using XDebug and WordPress; especially when dealing with permalink structures. Instead, you can ignore those buttons and click the “Start Listen PHP Debug Connections” button on the toolbar (that looks like an old telephone handset) followed by opening your web browser and entering a special URL argument (which you can later bookmark). But before you can use debugging for the first time, you will need to let the file indexing process complete. Like Netbeans and other modern IDEs, PhpStorm pre-indexes your project files for faster editing and search functionality.

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 highlighted in red. 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 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 Fifteen theme in the theme’s subfolder. I.e. at /wp-content/themes/twentyfifteen/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.