I struggled immensely one evening to find a tutorial out there that worked for me, on how to debug PHP applications running over MAMP, using the PHP Storm IDE. After absorbing bits and pieces from other guides, what really made it click for me, was reading the official xdebug documentation, where they provide a diagram of how the debugging components communicate, and what some of the xdebug settings mean.
To point out… it doesn’t really matter that the PHP server in this scenario is MAMP, this configuration will work for any ‘remote’ PHP server. I put remote within inverted commas, because the server is actually running on my local machine, but is considered remote for the implementation.
What I had going on as my dev environment (but don’t let the exact details put you off, as the flow should be the same):
- MAMP 3.5, free version, running PHP 5.6.10 (did someone say PHP 7 was out?)
- Mac 10.10.5 (OS X Yosemite)
- PHPStorm (tested on 7.1.3 and 8.0.3)
Without further ado, let’s begin this winning guide, which by the way, was surprisingly straight forward to get working.
Setting MAMP up with xdebug
Xdebug is the life and soul of this debugging party – it’s a Zend Engine PHP extension that enables the debugging of PHP, as well as PHP profiling and other useful things.
Luckily for us, MAMP already comes with the xdebug extension out of the box, so we don’t need to bother installing it ourselves, we just need to make sure it’s enabled. We also need to ensure some xdebug settings are configured correctly. Let’s do both of these tasks at the same time!
Find out what version of PHP MAMP is running (Preferences > PHP):
As mentioned before, that’s version 5.6.10 for me. It’s important that we know what version is running, because we need to edit the active
php.ini config file. The PHP config file I’ll be editing is at
php.ini for editing, and search for
xdebug. There should be a setting that includes the xdebug Zend Extension, but it may be commented out. Ensure it’s uncommented, and also add some xdebug settings, giving you something that looks like this:
[xdebug] zend_extension="/Applications/MAMP/bin/php/php5.6.10/lib/php/extensions/no-debug-non-zts-20131226/xdebug.so" xdebug.remote_enable=1 xdebug.remote_host=127.0.0.1 xdebug.remote_port=9000 xdebug.idekey=PHPSTORM
Breakdown of PHP config settings:
zend_extension– make sure this value is the file path that points to the relevant xdebug module running for your PHP version in MAMP
xdebug.remote_enable=1– we are going to be setting up a remote debugging session, so make sure it’s enabled
xdebug.remote_host=127.0.0.1– Xdebug acts as the client, and the IDE (PHPStorm) is going to act as the server. This means that the remote host of the server is where the IDE is running, which will (probably) be localhost for you, i.e. the same machine
xdebug.remote_port=9000– PHPStorm, i.e. the server, listens for xdebug debugging on port 9000 as default, so unless you’ve got a good reason to change it, keep it as 9000
xdebug.idekey=PHPSTORM– This sets our debugging session key to
PHPSTORM. In theory, it can be named anything. Xdebug remote debugging uses session cookies to identify that a debugging session is in play. I’ll discuss this a bit more later on
Some of these above settings may already be the default for MAMP. So you might not need to explicitly set them all.
Restart MAMP servers, so that the
php.ini changes are applied, and visit the php info page (http://127.0.0.1:8888/MAMP/) to check your new configuration is live. Here were some screenshots of my applied settings:
You can also check if the Zend Engine xdebug extension is installed via the command line:
/Applications/MAMP/bin/php/php5.6.10/bin/php -v PHP 5.6.10 (cli) (built: Jul 6 2015 14:28:54) Copyright (c) 1997-2015 The PHP Group Zend Engine v2.6.0, Copyright (c) 1998-2015 Zend Technologies with Xdebug v2.2.7, Copyright (c) 2002-2015, by Derick Rethans
If you’re satisfied that the MAMP configuration is correctly setup, move onto the next stage – setting up PHPStorm.
Setting up PHPStorm
With MAMP out of the way, it’s now time to configure some options in PHPStorm.
Remember that PHPStorm is acting as the server for xdebug, and we configured xdebug (the client) to knock on the door of port 9000. Let’s first of all make sure that PHPStorm is setup to listen for incoming connections on port 9000.
- File > Default Settings…
- Use the search field to type in debug
- Focus in on the menu PHP > Debug
- Ensure that the Xdebug section is listening on port 9000
Here’s a screenshot of my settings:
Prepare PHPStorm, by telling it to begin listening for PHP debug connections. This is simply (but vitally) achieved by pressing a button in the IDE. Make sure you’ve got View > Toolbar showing, and look for the button that resembles a (proper old school) phone.
Here are some screenshots to guide you:
Thanks to some JetBrains documentation for that one.
Lastly, PHPStorm needs to be aware of our remote server (MAMP) that’s actually interpreting the PHP scripts. We’re going to point PHPStorm in the right direction.
Here’s a list of instructions, but see the screenshots below for further clarity.
- Edit a debug configuration, Run > Edit Configurations…
- Press the plus icon
- From the list, choose the option PHP Remote Debug
- Optionally give it a name
- Within the Configuration section, next to the Servers input, click on the ellipsis (…) to add a new server
- When the new window pops up, click the plus icon to add a new server (see below screenshots for details)
- Give it a name, such as MAMP. Set the host to 127.0.0.1. Set the Port to
8888 (or whatever your MAMP server is configured to listen to). Make sure Xdebug is selected from the menu. Click OK
- Now the server window has closed, you’re back to the PHP Remote Debug window.
- Enter your IDE key, matching the same one as set inside of the
php.iniconfig. That’s PHPSTORM for us
- Click OK. You’re done!
Thanks goes to more JetBrains documentation on this.
Debugging PHP in PHPStorm
Finally, we’re getting to the good stuff. Get your debug configuration running, by either making sure it’s selected in the drop menu next to the bug icon, and clicking on the bug icon to activate. Or from the menu – Run > Run…, then choose the debug configuration you created earlier. Here’s a screen grab of the former method:
Upon activation, a debug bar should appear at the bottom of PHPStorm, that says it’s waiting for connections (Waiting for incoming connection with ide key ‘PHPSTORM’):
To test our example, we’ve got an
index.php file sitting in the
htdocs of our MAMP server, with the following content:
<?php echo 'Code Chewing';
Stick a break point on line three, like so:
Open your browser, and navigate to http://127.0.0.1:8888/?XDEBUG_SESSION_START=PHPSTORM
Your breakpoint should get hit, automatically switching windows to PHPStorm. You’ll see something like the following:
You can see that I’m inspecting the
$_GET variable, where I can see the
XDEBUG_SESSION_START key. This will also exist in
Xdebug sets a cookie in the browser, which links up with the DBGp protocol, and the rest is beyond my understanding in all honesty. But it essentially enables the debugging session to ride through the various components to provide the debugging experience. Go knock yourself out with the docs if you fancy it.
The cookie expires after an hour. And if you take a peek at the request headers, say through the browser dev tools, you’ll see a cookie being set:
Set-Cookie:XDEBUG_SESSION=PHPSTORM; expires=Fri, 08-Jul-2016 23:01:22 GMT; Max-Age=3600; path=/
This means that for the next hour, you don’t need to pass the query
XDEBUG_SESSION_START=PHPSTORM through to the HTTP request if you don’t want to, and the debugging will still be active. Yay for cookies! Meaning that you can hit http://127.0.0.1:8888/ instead of http://127.0.0.1:8888/?XDEBUG_SESSION_START=PHPSTORM for subsequent requests.
But query strings aren’t cool!
Well, there are some bookmarklets that you can add to the browser which eliminates even the need for manually entering the query string, and you can generate them here:
I hope you’ve now got to grips on how to debug PHP using MAMP, via xdebug and PHPStorm.