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?


  • 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


  • 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



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


  • 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])


  • 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.


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

12 Replies to “Installing and using PHP Eclipse IDE on OS X”

  1. I’m a little surprised at how much effort the installation was. Two points that strike me:

    1. I don’t have Stuffit Expander because OS X’s builtin archive expander works just fine.

    2. You might want to look at NetBeans. 6.5 is meant to have much better <a href=””PHP support. I tried NetBeans for Ruby and found it to be lots better than the equivalent Eclipse plugin. Just to warn you: 6.5 is currently RC and due to be released properly “any day now”.

  2. Of course, there are much easier ways to write PHP on a Mac. I think a lot of your problems stem from the fact you want a proper “IDE” (which is not really how I like to develop scripting languages).

    Most of your problems stem not from the fact that PHP development is hard on a Mac, but that Eclipse is a total PITA. But, you know, if you want an IDE for PHP development, it probably is your best option.

    And to say that “OS X can’t unzip the files”; well, it can, just fine, and you do it from the terminal. Whilst the Eclipse way of unzipping into existing folders isn’t the default, you can either (as you prove) use the terminal (which means that OSX *can* unzip the files) or you can unzip it elsewhere and just drag stuff over.

    Alternatively, a decent text-editor with highlighting, syntax completion, code snippets, preview and project handling (for instance, Textmate) is a single-click install, and then you just need to enable that PHP5 module in your apache2.conf and you’re off, developing inside ~/Sites .

    I understand that your goal was to use Eclipse, but I’m really not sure why, when much more straightforward (and just as effective) solutions exist. To leap from “I wanted to develop some PHP” into “I need Eclipse” clearly is more of a can of worms on OSX than other platforms, but other development enviroments, and paradigms, are available.

  3. @Dominic – thanks. I’m heavily biased against NB I’m afraid, but if it works for you / others, then great. Worth a try – some people like it

    Sadly, having used Netbeans (and it’s precursors) a lot, I hate it with a passion. I re-try it about once every 1.5 years, and each time it quickly brings back so many painful memories that I run away screaming.

    Well, not really :), and I haven’t tried NB 6, so I’m overdue a re-eval – maybe I can finally banish those demons ? :) … so far, IME it has consistently been “not as good as Eclipse” since Eclipse became viable. The performance monitoring from NB 5 (IIRC) was much better than Eclipse, and so for a while I used both in parallel, but NB was painful even just using it for that.

  4. @Tom – FYI, coincidentally, this is the first time I’ve specifically done PHP within an IDE. Mostly because there weren’t viable IDE’s for PHP the last time I was coding with it, and partly because I was usually doing small projects or just minor maintenance of other people’s stuff.

    However, nowadays IDE’s have advanced so much that I consider it foolish in the extreme to do any programming without one, and there are so many *free* IDE’s of awesome power that I see it as pretty much inexcusable too.

    I agree that this is largely Eclipse’s “fault” – but OTOH the eclipse maintainers have no responsibility for what is done with plugins, and some plugin authors do what it takes to make Eclipse installs tractable, so I can see that you could argue it either way.

    re: IDE usage … I guess that there are still people who hate re-factoring, or refuse to do TDD, or “don’t trust” build systems, or who use no libraries and few functions in any of their programming (I’ve met people like that, so I know at least *some* exist, somewhere). They could all get away without an IDE. But I think most of us are addicted, and can’t. Personally, I refuse to do any programming without a refactoring IDE – what’s the damn point? Overall these kinds of things massively increase your productivity and remove wasted + lost time. At no cost. What’s not to love?

  5. @ Eclipse webmaster – don’t get me wrong, Eclipse is awesome in many ways.

    It’s just been consistently over-complicated and under-explained to get started with. It has a very steep learning curve *to no benefit* – there’s nothing inherent in the application or it’s use-cases that requires that much complexity and opaqueness (i.e. AFAICS most of the complexity could be automated with no loss of flexibility or user-control).

    Obviously, any change requires manpower, so I’m sure it will get fixed “eventually” but in the meantime it’s just not a nice experience for first time users :(.

  6. Easyeclipse is 1.5 years and 1.1 versions out of date – and that’s the cutting-edge, only-partially-working version. Very few developers I know could live without the latest version of eclipse as the bugfixes tend to be legion and the new features tend to be incredibly powerful.

    So…IMHO: nice idea but currently a waste of time.

  7. Hi. I know it’s OT, but how is the performance of Eclipse on your air? And which version is it?

    I’m a heavy Eclipse Java user and looking at the air for my commute, but need to know it is useable every day for eclipse development.


  8. Eclipse runs very fast on the Air. I worried about that a bit too, having had previous bad experiences of OS X and big apps (photoshop etc), but I’ve had no problems.

    If it hadn’t had 2Gb RAM I wouldn’t have bought it. That’s enough that I can safely run Eclipse x 2 + Xcode + OpenOffice + several hundred web browser windows + a handful of graphics apps (2 bitmap apps, one vector app) … and everything’s fine.

    Eclipse does get swapped out to disk a bit more aggressively than other OS X apps, I’ve noticed. I don’t know if that’s due to eclipse’s code, or because OS X is giving the “more native” apps some kind of preference. If you stop using Eclipse for a day or two, and churn some other big apps in and out, you might have to wait 5-7 seconds for it to fully load back into RAM.

  9. Thanks. I’ve just ordered a second Gen 1.6 HDD version on your recommendation. So if it doesn’t do the job, I’ll know who to blame!

    Cheers for taking the time to reply :)

Leave a Reply

Your email address will not be published. Required fields are marked *