Installing and using PHP Eclipse IDE on OS X

I wanted to knock something up for Facebook, and I thought I’d try out PHP development on my shiny macbook air laptop (I usually develop on a much more powerful windows/linux PC).

This is tortuous, painful, and mostly undocumented on the official site. Sigh. After some experimentation, here’s how to make it work (IMHO you shouldn’t need to do this – although the Eclipse project allows plugin developers to package their plugins in really stupid ways, and doesn’t make it easy for anyone (users, developers, etc) – it’s still the fault of the plugin developer if they ALSO do not make it easy for the users to install).

First problem: get Eclipse

IME, most programmers who would use Eclipse already have it. The PHP plugin website won’t really help you, mostly taking the attitude of “install an extra copy of eclipse, just for doing PHP development; if you already have eclipse … work it out yourself”. I kind of understand why, but still feel that the first duty of every developer is to make their stuff easy to install!

If you don’t have Eclipse, I highly recommend you do NOT follow the PHP instructions (by downloading their pre-made “PHP + Eclipse all in one”) because then you are doomed to having multiple parallel installs if you ever need to use any other programming language; learn how to do it properly instead.

Download eclipse here (you want the latest stable version, currently called “Ganymede” (no, I don’t know why they stopped using Version numbers either – yes, it does make life more difficult for all normal users who haven’t memorized the funny names. Sigh)). You can get “Eclipse with Java” or “Eclipse with C/C++” or whatever you want – they are all identical, some just have extra plugins pre-installed.

NB: the people that run the Eclipse website have some pretty icon-artists, but a cruel sense of humour (or just suck at website design, maybe? I shouldn’t complain – it used to be a LOT worse than this) and don’t provide bookmarkable links to the OS X version (that I could find, at least); you’ll just have to go to that page and scroll till you find it. Right now, the current “standard” Eclipse version is at the VERY BOTTOM OF THE SCREEN (c.f. my previous comment re: sense of humour), and at the right hand edge of that box is a tiny link saying “Mac OS X”)

If you’re new to Eclipse, you will probably find that downloading eclipse is one of the most confusing downloads you’ve ever done; if so, this is part of that same problem mentioned above where the Eclipse project makes plugin installs ridiculously difficult: all those many confusing different Eclipse versions that you cannot tell the difference between are actually the same, but differ only in which plugins are pre-installed.

Yes, this is stupid. Yes, it’s badly documented. Sorry. You’ll learn to live with it – they’ve been doing this for almost ten years now so don’t expect it to be fixed any time soon.

I suggest you run Eclipse once, now, before going on to the next step – if Eclipse doesn’t start at this point, don’t waste time confusing yourself with the PHP plugins until you can get Eclipse working on its own!

Second problem: get PHP IDE (now renamed to “PDT”)

You can try to do the automated-install; Eclipse is bad at handling automated installs, has very poor error-handling if anything goes wrong (it just crashes and doesn’t explain), and plugin developers usually screw-up the auto-install API in ways that can actully render your copy of Eclipse unusable (this happens *a lot*). I would advise never using it if you can avoid it.

This one’s pretty messed-up. According to the website and the list of requirements, if you want to use the latest version (vesion 2.0, not yet “packaged”), then you have to download approx 6 massive files.

I found that if you download the “Eclipse for Java” pacakge then it has some of those built-in already, and even if you don’t, several of those have EACH OTHER built-in (WTF?). I suggest you don’t take any risks, and that you do this the long way (download EVERYTHING).

First, go to this download page.

Decide which version you want; right now you want “2.0.0 Stable Builds”, but soon that will be what you get from “Latest Releases”, so check there too.

Then download ALL the zip files listed under “PDT” AND everything listed under “Build Dependencies”. Right now, there are 3 files for “PDT” (SDK, Runtime, and Tests), and 5 files under “Build Dependencies” (Eclipse gtk, EMF, DTP, GEF, and WTP).

Third problem: OS X can’t unzip the files

If, like most OS X users, you’re using Stuffit Expander to unzip the files, by default it won’t do it, because they all overwrite the same directory name (and StuffIt is designed to “protect” you from that, which is nice).

That’s only slightly annoying to get around, but you are still screwed, because OS X itself is (apparently – I couldn’t find a way around this using Finder) hard-coded to prevent you from copying the contents of the directories into the Eclipse directory. When you try to it says “delete the target directory first, or cancel?” (unlike windows, which says “only overwrite files which are the same, otherwise copy all the missing files … or cancel?” which is 99% of the time what you wanted. I have no idea why Apple uses a “destructive” copy – and gives you no alternative!)

Here’s how to get around both problems: The solution – Manual install via Terminal

Fortunately, if you switch to using the Terminal, and run “unzip” by typing it in manually, by default it’s setup as a unix variant that acts in the same way that Windows works by default.

First, make sure you are in the directory where you saved the ZIP files, e.g. by typing:

cd ~/Downloads

(assuming you saved them to your personal Downloads folder)

Then you just type:

unzip [name of zipfile1]
unzip [name of zipfile2]
…
unzip [name of zipfileN]

…which resolves the incompatibilities in the distro files, and then to install the plugin you type:

cp -Ri eclipse [location of your eclipse folder – usually: /Applications/eclipse]

Note that the “-R” is *required*, and that there is NO trailing slash after “eclipse”. The “i” after the “-R” is optional, it might be good to know if you have problems, but it allows you to get confirmation before overwriting any files. Thankfully, you can just hold down the enter key and it will do the defautl (do not overwrite) as it goes through each file; there are many hundreds of files to copy, and you may already have hundreds of them, so this is handy.

Installation complete

Now start Eclipse – this took 5 minutes for me, where normally it takes 30 seconds, don’t ask me why) – but eventually it worked.

Test it works – go “File -> New Project” and scroll down to the PHP folder, and select “PHP Project”. If there is no PHP folder in the list, then the install has failed. Start again. Good luck.

Otherwise, it should let you create a project, in which case: You now have PDT / PHP-IDE for Eclipse installed and working.

Writing a PHP file

I’m assuming you know how to do this, or can find a tutorial (any PDT tutorials should be fine – it works the same way as the mainstream language plugins for Eclipse, so *any* tutorial on creating a source file and building it ought to work).

Fourth problem: Running your PHP

Oh crap. If you go ahead and create a project, give it a name, and hit OK, you’ll find that the PHP IDE seems designed to not allow you to develop or test PHP on a server; it only supports developing and testing on a local (inside Eclipse) private PHP interpreter. If you’re new to programming, this is fine to get started and learn some basic PHP.

If you’re an experienced programmer, you’ll probably hat that: unless you enjoy tracking down unreproducable bugs and tearing your hair out, you need to develop on the same software + version that runs your production server (in most cases, this will be an Apache2 server running the PHP5 module). Since OS X comes with Apache2 *and* PHP5 built-in, you *already* have a server on your machine that is probably 98% the same as the live server you would use (so far Apache2 + PHP5 on OS X seems to act almost identically to the same versions on Linux, FreeBSD, etc – as you would expect).

(98% is annoyingly short of 100%, but it’s a lot closer than using the bulit-in interpreter)

I can’t find any options in the Run Dialogs to control how it invokes the running of the code from a remote server (or even a local one!) – if you go digging through all the config options, they’re just missing.

NB: there IS something that looks like it might do the trick, where it has a list of “Server” and lets you choose a “PHP Server” – but THIS IS A LIE (there is no cake), do not believe it, this is for something else entirely; it’s just that someone made a poor choice of name for those labels).

Instead, what you have to do is be a lot more careful when creating new projects. Do this:

• File -> New… -> PHP Project
• Fill in project name as per normal with Eclipse
• UNcheck the “default” option for “Project Contents”
• Click the Browse button under “Project Contents” and navigate to wherever you keep your source DIRECTORIES for all your projects (see more on this below – and you may end up crying when you see what has to be done)
• Click Finish
• …NB: BE CAREFUL: it asks you a sneaky extra question, and your answer depends on how you manage source control (see below)

Special Note: where do you keep your PHP?

If:

• you are just developing locally for now on OS X
• AND you want to use the Sites directory to save your PHP files in
• AND you want to use your Apache2/PHP server instead of the “fake” one that comes with eclipse

Then:

• select your personal Sites folder as the Project Contents above
• AND answer “Create project in /Users/[your name]/Sites/[project name]” when you press Finish above

This will:

• automatically create a new sub-directory in Sites with the same name as your project
• mean that the address of your project is “http://localhost/[projectname]/”
• mean that if you delete the project in Eclipse, and select “delete from disk as well” when you do, Eclipse will delete ONLY the “[projectname]” subdirectory from your Sites folder, and leave everything else intact

…ALTERNATIVELY…

If:

• you use proper source control which has a unique root directory for each source project

Then:
EITHER:

• select the folder for that project as the Project Contents above
• AND answer “Create project in [source root folder]. (Deleting the project will delete the entire [source root folder])

OR:

• select the PARENT folder that contains the project-specific source folder as the Project Contents above
• AND answer “Create project in [PARENT folder of source root folder]” when you press Finish above

I actually strongly recommend the first option, since this will ensure that Eclipse doesn’t mess with your source control’s PARENT folder (which in most source control systems will either screwup the system (happens with crappy source control like CVS) or just be ignored because you won’t have write-access (happens with the more high quality source control) – but this can upset Eclipse if you do some other things wrong in the future.

FINALLY!

After all that, I finally had a working PHP IDE on OS X. Yes!

I haven’t tried debugging yet, but I found the following links that look pretty sound for setting it up. Bear in mind that the first one tells you to setup your Project Contents differently – just adapt what it tells you depending upon what you did above – the author doesn’t seem to fully understand Eclipse’s arcane approach to projects (given the name he uses for his Project!), which is fine, but IMHO not recommended.

How To Setup a Free PHP Debugger using Eclipse PDT + XDebug