Using Xdebug in MAMP

My current web development environment basically consists of a Macbook Pro running Mountain Lion, PHPStorm 5.0 and Virtual Box running one ore more virtual Ubuntu Servers with everything needed. Correctly setting up a linux guest OS in Virtual Box with shared folders shouldn’t be but is sometimes a bit of a headache. (Even though it does have many advantages.) Others choose not to use virtual servers and instead go for  MAMP when using OS X.

MAMP is a full local server environment including Apache, PHP and MySQL in one package. Anyone feeling at home in *nix systems should feel at home using both OS X and MAMP. It is easy to install and use even if you don’t care much for the terminal or configuring Apache, PHP or MySQL. As I have helped a few collegues setup Xdebug in MAMP I have discovered that a lot of developers don’t do this as they don’t know how simple it is. Even seasoned PHP developers use the old echo/die debugging techniques.

So I thought I’d write a small guide on how to setup debugging using xdebug in MAMP from PHPStorm. The process is similar if you use Zend Studio or another IDE of your choice. Only the IDE configuration should be different. If you already have MAMP installed just skip directly to the PHPStorm part.

MAMP

Installing MAMP is as easy as downloading it from http://www.mamp.info/. Double click to unpack the zip file. Then double click the the pkg file and follow the instructions. MAMP is installed in /Applications/MAMP and Xdebug is already included, though not enabled. By default MAMP (in version 2.1.1) use PHP 5.4.4 and has Apache listening on port 8888.

To enable Xdebug in MAMP locate and open the file /Applications/MAMP/bin/php/php5.4.4/conf/php.ini using a text editor of your choice. Locate the [xdebug] section, right now in the bottom.

[xdebug]
;zend_extension="/Applications/MAMP/bin/php/php5.4.4/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so"

The semicolon means the line is commented out. Remove the semicolon to make PHP load the xdebug extension. You will also need to add a few configuration directives to setup xdebug locally and to trigger automatically. The complete xdebug configuration should look like below.

[xdebug]
zend_extension="/Applications/MAMP/bin/php/php5.4.4/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so"
xdebug.remote_host=127.0.0.1
xdebug.remote_enable = 1

That’s it. Next time you start (or restart) MAMP, xdebug is enabled and ready for your next debugging adventure.

Create something to debug

I assume you already have PHPStorm installed or know how to install software on OS X. In PHPStorm, open the directory /Applications/MAMP/htdocs. This is the default web root in MAMP. Create an index.php with the following content.

<?
  function testFunc($number) {
    echo 'Hello nr ' . $number . PHP_EOL;
  }
  $n = 0;
  while($n++ < 4) {
    testFunc($n);
  }

Setup debugging in PHPStorm

Select the menu Run > Edit Configurations… to open the Run/Debug Configurations Dialog.
Click on + and choose PHP Web Application.
Give it a name like “My first debug”.
Add a server. Click the button “…” where you specify server. The Servers dialog opens.

Click on + and fill in the values below.
Name: “MAMP Server”
Host: 127.0.0.1
Port: 8888
Debugger: Xdebug
(In this setup you do not need path mappings. You would need path mappings if doing this with virtual servers and shared directories though.)
Click OK to save and return to the Run/Debug Configurations dialog.

Choose your browser or use default.
It should now look like the screenshot below. Click OK to save and return to PHPStorm. You are now ready to start debugging.

Start debugging

If you don’t already have the file open you created earlier. Open it and click in the margin to add a breakpoint. For example, add a breakpoint to line 3. It should now look like below.

To start debugging, press the rightmost “green arrow with a bug” in the button bar. PHPStorm will now either open your browser or create a new tab in your browser pointing to an address very similar to http://127.0.0.1:8888/?XDEBUG_SESSION_START=18458. The get parameter XDEBUG_SESSION_START tells xdebug in PHP to start a new debugging session and connect to PHPStorm to let you debug. Immediately after the browser opens the page PHPStorm should come into the foreground and be paused on line three where the breakpoint is.

As you can see above you can now investigate variables while stepping forward one line at a time. Just remember to stop your debugging session by clicking the Stop button (red squary) when you’re finished debugging. Otherwise you will experience weird behaviour you might not understand immediately. Familiarize yourself with all the ways you can step through your code and life will get a lot simpler.