PhpStorm 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 commercial 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. However, first setup is a challenge as placement of user interface elements is less than intuitive. 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 debugging quick, robust and even more responsive than Netbeans’ typical debugging sessions.

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 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 www.example.dev 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 site 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 website, we’ve selected the ./Documents/Websites/www.example.dev 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. Then fill out the personalized “Web server root URL” field as it was created in DesktopServer, i.e. http://www.example.dev. 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.

Important! PhpStorm will prompt you to “Specify a Web Path”. Leave this field blank, but be sure to click the checkbox option to “Review PHP Settings”. This is important as we’ll need to modify include paths to allow DesktopServer to work with PhpStorm correctly. Currently, DesktopServer does not support PHPUnit. We will update PEAR and provide PHPUnit support in a subsequent version. For now, simply click the “Next” button to review and modify the PHP configuration to work with DesktopServer and your WordPress development website.

Very Important!  At this point, PhpStorm should display PHP configuration information. Be sure to modify the include path(s) to match your platform. See the screenshot to the right for your system.

If you are on Windows, remove the ‘PEAR’ part and make sure that the include path c:\xampplite\php is present. If you are on Macintosh, remove the /lib/php/pear and ensure that the path to /Applications/XAMPP/xamppfiles/etc is present.

DesktopServer is designed with specifications that matches most modern hosting providers to make deploying your WordPress website less complicated. WordPress requires a minimum of PHP 5.2.4, but most hosts use PHP 5.3.  Be sure to set PhpStorm’s language level to 5.3 as its default is 5.4. Use Ctrl+Alt+S on Windows or Command+, on Macintosh to bring up the PhpStorm Settings panel and select “PHP” in the settings list. Use the drop down combo box for “PHP language level” to set the value to 5.3.

Debugging WordPress in PhpStorm

PhpStorm’s web debugging is a bit awkward [for the first time]… Despite this clumsy process, the user interface for debugging is significantly faster than Netbeans and well worth the initial burden.

Starting PhpStorm’s web debugging is a bit awkward and somewhat cumbersome when you use it for the first time in a given project. It departs from traditional IDEs that feature start and stop buttons that automatically open your web browser to kick off a debug process. 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. You will also have to answer a security dialog with an ‘Accept’ button to authorize the XDebug connection. Thankfully, initial indexing is a one time process required before the debug button is enabled on the toolbar. The ‘Accept’ debug authorization dialog is also remembered for your convenience. When you first create your project from existing source files, PhpStorm will automatically start indexing all of your files.  If indexing doesn’t start automatically (and it failed for me on both Mac and Windows on more then one occasion), you’ll simply need to close PhpStorm and re-open your project. Despite this clumsy process, the user interface for debugging is significantly faster than Netbeans and well worth the minor, initial burden.

The “Start Listen PHP Debug Connections” button will have a little telephone headset icon that should turn from red to green when clicked and enabled. You can then open one of your source code files that you would like to begin debugging or editing. In our example below, I have opened the index.php file from WordPress’ default twentyeleven theme and placed a breakpoint on the source code line “get_header();”. To kick off the debug process, simply open your favorite web browser and enter the URL of your development website followed by the debug parameter “XDEBUG_SESSION_START”. For instance, to start debugging our example website’s home page, type http://www.example.dev/?XDEBUG_SESSION_START on the URL address bar and press enter.

 

The PhpStorm debugger will color the current line of code that the instruction pointer is about to execute blue. In our example below, the blue line will be the first breakpoint that PhpStorm encounters (the breakpoint we set for the “get_header();” line of code in our twentyeleven/index.php file). You can use the step buttons to “walk” through code logic to help you understand how WordPress, plugins and theme files work. Use the “Watches” window to examine local and global variables. You can stop the debug process at anytime by clicking the red square icon in the side pane of the debugger tab.
You can hover your mouse pointer over pieces of PHP code to reveal variable contents while the instruction pointer is stopped. PhpStorm will automatically provide floating popups that reveal variable values or a ‘+’ symbol to examine more complex data structures. PhpStorm provides additional windows that appear below the main code editor to show context variable values and a “Frames” window (a breadcrumb history of files processed before the breakpoint was encountered).

Last Notes

Regardless of the initial less than intuitive web debugging process, PhpStorm appears to match NetBeans in several key debug features and goes beyond with a more responsive and snappy feel. Performance is definitely kicked up a notch and key features like floating variable hints “just work”. This useful and touted NetBeans feature has never worked right in Netbeans and is currently broken in version 7. But it works really well in PhpStorm. In addition, the variable watch window and inspectors appear to be more consistent while stepping through code and refreshes are considerably faster than Netbeans. PhpStorm appears to also match Netbeans on a feature by feature basis with almost identical popup context menus for code navigation abilities like “Find Declaration”,  ”Find Usages”, and included built-in difference tools. In fact, checking out the overview of features in the my “Using Netbeans for WordPress…” post easily matches PhpStorm in almost every aspect, but with the polish you’d expect from a paid commercial product. Give it try; it might just be the productivity boost you’ve been looking for in a dedicated PHP editor.

Tagged , , , , ,
About Stephen Carnam
I’m a San Diego, California based computer programmer and graphic designer that has been consulting, developing, and maintaining web & software applications for well over ten years. My languages and interests include PHP, Java, JavaScript, 3D rendering/sculpting, and snow boarding.

8 Comments

  1. devinwalker says:

    Great article Stephen. Awesome information about PHPStorm and WordPress debugging!

  2. cptdoom says:

    Hi
    thanks for this tutorial. I just downloaded phpstorm 4 on Win8, but the Debug window isn’t being displayed and it’s greyed out under View – window – debug
    any ideas how ti fix?

    1. Stephen Carroll says:

      It appears that the debug window won’t be available until you are actually stopped on a break point.

  3. emzero says:

    I really like JetBrains products. RubyMine is great for debugging rails projects, but even though the debugger is faster and better than Netbeans’s, having to append the XDEBUG_SESSION_START on every page you want to debug it’s just too clumsy.

    Netbeans only appends this in the index page, when you click the play button, then you can navigate the site normally and the X:DEBUG_SESSION_START is stored in the cookies so you don’t have to append it.

    Is there any workaround to make something similar in PhpStorm?

    1. emzero says:

      Well I made it work with the play button and without having to manually add the XDEBUG parameter.

      This is what you need to do:

      1) Go to Run > Edit Configurations
      2) Click the + and add a PHP Web Application
      3) Name it as you like and set the server as your http://www.example.dev. Start url can be /
      4) That’s it!

      Now you can click the play button and start debugging any page you want =)

  4. zunxin says:

    A debug problem in wordpress exists for a long time!
    Details:
    1. place a break point on: require_once( dirname(__FILE__) . ‘/wp-load.php’ ); // in wp-blog-header.php
    2. begin debuging, after it hit the break point, press (Step Over) button, the whole thing will stop.
    Do you know the reason?
    Thanks in advance!

    1. Stephen Carroll says:

      This problem might be because the XDEBUG_SESSION_START parameter is lost when going into another file. You may wish to try emzero’s trick above.

      Otherwise you may be able to safely place a break point above, below or inside the include file line.

      1. zunxin says:

        The debug process will terminate once it goes through
        this line
        $wp->init();
        in this file
        wp-settings.php.

        I tried many times and can not figure out the reason.

        wp-settings.php will be used in nearly every normal page request, so I have to make extra change in functions to make it pass, including the functions bellow:
        wp_get_current_user
        is_user_logged_in
        get_userdata
        just make them just return null will be ok, the debug process will be no problem,
        But I want to know the reason.