5 Step Tutorial: PHPStorm + MAMP PRO 2 + XDebug+PHPUnit + SkelGen and Code Coverage on Mac OS X SL

OMG,  :^O  this has been a challanging thing to accomplish but I figured it out and to help others who may experiance similar issues I will make this painless for you.

Ok, so my normal editor of choice has been SubLimeText 2, Oh how I love this editor but it can be a real pain to get complete debugging, unittesting and code coverage using Sublimetext without the use of external tools. This means switching back and forth between several different programs to accomplish what PHPStorm can do out the box. Don't get me wrong, I love sublimetext but I got work to do and running several programs is not working for me. Sure there are some plugins for sublime that make it a little less painful but not painless enough. So I downloaded PHPStorm and WOW...

Ok, So first thing we need to understand is that the dev's over at apple are not playing nice for having a posix compliant OS. Yeah, Yeah I know it's a Mac but still, my thought pattern has always been that Linux and Unix based OS's have a lot to offer and everysince OS X made it's intel debut running ontop of a posix compliant core well let's just say I felt somebody somewhere was using their brain. Now if we could get M$ to do the same with windows and get them to understand one thing.

LEAVE THE INSTALLATION OF SERVER PROFILES TO THE USERS.... X-( That's right and here is why, as it stands OSX ships with Apache, PHP, Java and Python installed and you would be hell bent on even tampering with those installations because you don't have inside knowledge as to what dependencies OSX is applying to these default installs nor if apple dev's altered the core for their own purposes. Bottomline is these are pretty much no touch installations, no upgrade, no nothing. But what if you want PHP 5.4 or the newest Apache install. This is where they don't play nice, even with macports and fink as non offical repos you still will end up with multiple installations of certain applications. You would think that since the guys and gals over at macports did all the work that apple would give them a bone and make it the official repo so things get installed gracefully where intended providing an upgrade path while in between major OSX releases. Oh, I found out the hard way that if you tamper with anything and need to revert back you cannot just pop in the OSX disc and repair Oh No you must reinstall the entire OS.

I PREDICT: ]:) That one day all OS vendors will come to the realization as apple did, that you can have a proprietary OS that sit's nicely on a posix compliant core that will close the gaps between systems and make everything play nicely. Well, not everything as the GUI shell is still Mac or Windows or KDE or whatever and in order to get an app on their you have to code for that environment but underneath all that is an open world where tons of software applications already exsist and can coexsist with much fanfare. Are you listening M$ get with the program and apple, get with the repo program.

So on to the challange and quick but otherwise dirty solution to set my MacBook Pro up as a Dev workstation. This first point goes back to my little speech above. BOTTOMLINE is that PHPStorm will use the default installation of PHP as installed by apple no matter what interpreter you tell it to use (it's all about paths and environmental variables folks and you can verify this by opening a command line from inside the IDE and running which php), this will lead to all kinds of funny stuff happening when using a prebuilt stack like MAMP so, what if you are one of those Dev's who just want to install MAMP, XAMPP or AMPP? Yeah sure we could install MySQL and all the other bells directly to the default OS but some of us want to have a portable dev environment and using a pre built stack gives you this. By default ALL mac apps are portable, just load them up on a USB stick and your Dev environment will work on any MAC that meets the requirments of the applications on the stick. Just pop it in and Code till you drop. Now I haven't tried this but I would imagine that since all of these stacks are cross platform including PHPStorm you could easily copy your IDE profiles and clone VCS repos onto other stacks that live on USB sticks and have a goto Dev environment that is portable across all OS's. Will have to try that. But anyway it sounds appealing don't you think? :D

Ok So here we will be setting up a complete PHP development environment on Mac OS X Snow Leapord. We will not be too redundent here as I expect most readers to at minimum already know the basics of running MAMP, GIT and simple things like that. Here we will focus on getting PHPStorm, MAMP, PEAR, APACHE, PHP, PHPUnit, and XDebug Playing nicely.

NOTE: When I did this it was all trial and error and of course I have  edited this document to provide a logical sequences of steps to help  you get going this in no way reflects what actually happened to me or  the order of which I have delivered it to you. I was FUBAR, a chicken  with no head as I had expectations that did not simply exsist.

Step 1: Install PHPStorm.

Just Download PHPStorm from http://www.jetbrains.com/phpstorm/download/index.html Then double click the .DMG and mount it. It should open automagically to the screenshot below. Just drag the PHPStorm Application to the ------>>>> Application Folder and your done. Of course you will need to execute that Application to setup defaults and enter licensing but hey you already got that part right? :p Moving on ...

Step 2: Install MAMP or MAMP Pro.

Now, Let's download MAMP from http://www.mamp.info/en/downloads/index.html MAMP installs both the standard MAMP (Free) and the Pro Edition (cost about 59.00 USD) with the latter in trial mode. Pick your flavor and lets's get to it. Open the disk image (you will see the screenshot below) and drag MAMP into your Applications folder. I know, yeah redundency but hey it's bout to get harder. ;)

I would assume that you have already setup your MAMP stack properly by setting the proper ports and tested this all out. We won't be covering that here.

NOTE: YOU WILL NEED ADMINISTRATOR ACCESS TO INSTALL MAMP CORRECTLY

Step 3: Installing/Upgrading Pear to live inside your MAMP stack.

Now I've seen alot of folks have issues with this step but it really couldn't be any easier then what I will show you here. In order to install PHPUnit, PHPUnit-Skel-Generator and Some of the other PHP dependencies we need to use PEAR. DO NOT ATTEMPT TO CLONE OR DL GIT REPOS !!! for these componants it will most likely not work and you will go through tons of coffee and aspirin trying to make it work. The main point and obvious reason is we need to get MAMP and it's PHP versions in the know about these componants exsistance for integration into the Stack.

We will open the OS X Terminal by doing a shift + command + U keystroke which will open the Utilities Folder where we will find the Terminal.app.

Double click on the Terminal icon to open the OS X Terminal. Mac uses a Bash command line by default so we have all the tools needed to get the job done.This will put you in your HOME (~) directory so you will want to enter the following cd ../../Applications/MAMP/bin/php/php5.3.6/bin

Now we have listed the directory and can see were in the bin folder of the php installation version 5.3.6. As you can see I have already done some installing as we have binaries for PHPUnit and PHPUnit-Skelgen. But to continue you can see there is already a PEAR binary inside the bin folder. MAMP ships with pear installed but we need to upgrade it. I followed the instructions from this http://bigdiver.wordpress.com/2011/11/10/mamp-2-0-pear-and-phpunit-installation/ post and experianced everything just as that author did. So I will edit and repost some of this here to save you time and blend in my trials and tribulations so lets issue the following command:

sudo ./pear upgrade pear

after I issued the upgrade command i got the following error:

 Notice: unserialize(): Error at offset 276 of 1133 bytes in Config.php on line 1050
 ERROR: The default config file is not a valid config file or is corrupted.

Don't Panic B-), No Problem here, If you get this error too, just delete the pear.conf file, and rerun the ./pear upgrade pear command. Like This:

rm /Applications/MAMP/bin/php/php5.3.6/conf/pear.conf
 sudo ./pear upgrade pear

downloading PEAR-1.9.4.tgz ...
 Starting to download PEAR-1.9.4.tgz (296,332 bytes)
 .............................................................done: 296,332 bytes
 downloading Archive_Tar-1.3.8.tgz ...
 Starting to download Archive_Tar-1.3.8.tgz (17,995 bytes)
 ...done: 17,995 bytes
 downloading Console_Getopt-1.3.1.tgz ...
 Starting to download Console_Getopt-1.3.1.tgz (4,471 bytes)
 ...done: 4,471 bytes
 upgrade ok: channel://pear.php.net/Archive_Tar-1.3.8
 upgrade ok: channel://pear.php.net/Console_Getopt-1.3.1
 upgrade ok: channel://pear.php.net/PEAR-1.9.4
 ...

./pear config-set auto_discover 1
 ./pear install --alldeps pear.phpunit.de/PHPUnit

./pear install phppunit

 Attempting to discover channel "pear.phpunit.de"...
 downloading channel.xml ...
 Starting to download channel.xml (804 bytes)
 ...
 install ok: channel://pear.phpunit.de/PHP_CodeCoverage-1.1.1
 install ok: channel://pear.phpunit.de/PHPUnit_MockObject-1.1.0
 install ok: channel://pear.phpunit.de/PHPUnit-3.6.3

This should print out the phpunit usage information without any errors, on the screen and in  your PHP Error log file. If there are any include errors in your PHP  Error file, you may have multiple PHPUnit versions installed and you  need to remove them all by using the pear uninstall command.

We will assume all went ok if you are seeing errors in your PHP error log file then revisit the original authors post and see if the example logs he posted match yours, if so follow his instructions to uninstall and reinstall phpunit go here http://bigdiver.wordpress.com/2011/11/10/mamp-2-0-pear-and-phpunit-installation/


Now, let us get PHPUnit-SkelGen installed on here. Again, following instructions from the PHPUnit Github repository, we will issue the following commands:

./pear install pear.phpunit.de/PHPUnit_SkeletonGenerator

You DO NOT have to issue ./pear config-set auto_discover 1 a second time as pear is already configured to auto_discover this repo based on us issuing this command when we installed phpunit itself. This will complete the installation of phpunit, it's dependencies and phpunit-skelgen. Let's test now to make sure phpunit-skelgen works as we expect.

As you can see we have output from the application showing the proper commands for usage. So we have now successfully got pear upgraded and phpunit with all that we need to work with PHPStorm installed. The point of this was, that by installing phpunit and phpunit-skelgen from inside the MAMP pear repo we insured that the environmental variables or shebang #1 /usr/local/env php in the phpunit scripts will parse correctly and point to the MAMP php installation NOT the default PHP install on Mac OS X. Trying this from a git clone or zip/tar download would rock your world because YOU would be trying to change this everyplace and of course by default it points to the OS X php install (or native home of php on posix compliant OS's).

PHPStorm Using MAMP based PHPUnit to run Test

UnitTest Stub Generated by MAMP based PHPUnit-SkelGen in PHPStorm


But hold on were not done just yet, :O we must add the MAMP PHP environment  that we want to use with PHPStorm to our PATH and also enable XDebug  within this environment lucky for us that MAMP ships with XDebug  installed it is disabled by default but nonetheless it is available.

Step 5: Add MAMP PHP to PATH and enable XDebug

Let's Start up MAMP. I'm using MAMP Pro 2.x it cost about 59.00 USD but allows me to quickly change the host file and gives me dynamic dns and a few other things that come in handy when developing web applications. If you use the standard MAMP installation your milage may vary however, I would not think it should be to much difference.

Ok so here we have MAMP Pro running and we need to edit the PHP.ini template for the 5.3.6 version were using. Now a word of caution about MAMP's ini templates. After much much headache and plenty of googling it is now my understanding that the php.ini file that is edited from the MAMP menubar is wriiten on each server start and actually lives inside the MAMP.app file that is inside the Application folder. This proved to be a great source of frustration as the first time I enabled xdebug using this method it worked fine when debuging web applications that launched a browser such as firefox but when trying to get code coverage working PHPStorm would report that xdebug was not enabled. Hmmmm, scratching my head, beating my head on the table, pounding my fist on the wall. ?:|

Ah Haaaa, :| I had discovered a few gotchas. To recap,

1. There are two ini files for MAMP, one that you access from the menu bar and one that lives in the /Applications/MAMP/bin/php/php5.3.6/conf folder. One appears to be self contained and only applies to the running web server (i.e actually using MAMP) and lives inside the .app file, the other controls what happens on the command line (regardless to if your running MAMP) which is where PHPStorm is applying configuration variables to the php interpreter for code coverage.
2. That PHPStorm IDE was reporting that XDebug was not enabled even though I could debug from the browser and even via remote from inside the IDE. I painstakenly figured out that PHPStorm was using the default OS X PHP interpreter (which I had not enabled xdebug for) even though internally I told it to use the one that came with MAMP which worked fine as long as I was working with Apache and writing code as it referenced the proper libraries for code completion.

So let;s get this correct the first time for you folks because you can trust me when I tell you I was frustrated enough for all of us. First we will edit the php.ini template accessing it from here.

Now edit your php.ini template to reflect the following:

So uncomment the xdebug extension which is at the very end of the ini template so you have the following:

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

xdebug.default_enable=1
xdebug.coverage_enable=1
xdebug.profiler_enable = 1
xdebug.profiler_output_dir = "/tmp"
xdebug.remote_enable=1
xdebug.remote_host=localhost
xdebug.remote_port=9000
xdebug.remote_autostart=1

Save the file and restart your MAMP server. You should now be able to test debugging by setting a breakpoint and launching a project in debug mode that has been setup as a web application in the IDE configuration profiles. Let's try it out and see what happens.

Firefox in break mode running IDE XDEBUG_SESSION

PHPStorm in Debug mode with breakpoint

Firefox showing that xdebug is working on this MAMP setup



Now Let's edit the php.ini file that lives in the conf directory so we can enable command line debugging using xdebug. If we don't then we can't use code coverage from the IDE. So using the GUI file manager in OS X navigate to the /Applications/MAMP/bin/php/php5.3.6/conf folder.

Mac OSX File Manager

You may need to set this file extention to open with your favorite editor (textedit, sublime, textmate or PHPStorm). We used Sublimetext 2.

Sublimetext editing php.ini from conf directory

Navigate to the bottom of the php.ini file and uncomment the xdebug extentions so it looks like this:

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

Save the file and close your text editor. We didn't have to restart the MAMP server because this file will be used for all non-server calls to php and will be picked up by the interpreter automagically. (not really but it does know it's there) ;)

Now this is where it got tricky for me, It took me a long time to even discover the presence of a second php.ini file as I was attempting to get code coverage working. Once I did though PHPStorm still reported that xdebug was not enabled. :_| This is when I had a fit, but then it dawned on me that maybe, just maybe the IDE was not using the correct version of PHP so I opened a terminal and typed which php and discovered that my PATH was pointing to the default installation that comes with OS X. So let's alter that so when we open the terminal we can use the MAMP PHP stack. Type the following in your terminal:

$ echo "export PATH=/Applications/MAMP/bin/php/php5.3.6/bin:$PATH" >> ~/.profile 

Then do this to restart your profile

$ . ./.profile

Now let's check to make sure it's all working by type this:

$ which php
/Applications/MAMP/bin/php/php5.3.6/bin/php

$ which pear
/Applications/MAMP/bin/php/php5.3.6/bin/pear

$ which phpunit
/Applications/MAMP/bin/php/php5.3.6/bin/phpunit

$ which phpunit-skelgen
/Applications/MAMP/bin/php/php5.3.6/bin/phpunit-skelgen

The PHPStorm IDE Tool Menu

Doing this created a script called pstorm and we saved it to the default location that was reccomended by the IDE which was in our PATH. We then closed the IDE and relauched it from the command line by typing pstorm and OHHHHHH YESSSSSSS we got code coverage .....

Code Coverage in PHPStorm from MAMP based PHPUnit

Well that's it folks I hope I didn't forget anything and I really hope this helps someone else. I won't lie I wish I would have found something like this from the get go. Would have saved me a couple years of age stressing over getting it done but my pain is your gain. Please if you find I missed something let me know and hopefully I can edit this post and make it right. As I try and get Phing and PHPCS installed within the MAMP stack I will update this post so others may follow.