Drupal Association members fund grants that make connections all over the world.
Eclipse is an open source IDE (Integrated Development Environment), that provides many tools for coding in one application... the most useful of which is probably PHP debugging. This section will provide instructions for installing and setting it up for use with Drupal.
Eclipse is a Java application so it can run on Linux, Mac and Windows, but comes with the price of a large memory footprint.
Hopefully this tutorial will help you setup smoothly. If not, stay with it. Getting debugging working is well worth the effort.
[Note: If any of this does not run smoothly for you, that's a perfect opportunity to help improve this page. Leave a comment or create an issue detailing the problem and how you solved it. You will be rewarded with a wave of karma!]
Debugging is probably the most useful feature of an IDE, so this tutorial will assume you want to set that up. To do so you will need to set up a local test server first. Without the local test server you will only be able to debug single file PHP scripts; for Drupal this is practically useless.
If you've not yet set up a test server you can find more information here. Go set it up and get it working with Drupal before you continue with this tutorial.
Installing Eclipse with Zend plugin
The Zend plugin will turn the generic Eclipse IDE into a PHP IDE. There are other options for plugins; Zend is just one of them.
In theory it should be possible to install Eclipse and then get the plugins working. In practice this may not run so smoothly! The easiest solution is to get the all in one package.
You can download the Zend bundle at the link below (it's about 100MB). It's called the 'All in one package':
Basic installation is easy. Simply download the appropriate package, unzip the file, and place the eclipse folder somewhere convenient on your drive. You will have to create your own shortcuts, start-menu items etc., since there is no actual installer. The main program file is called eclipse.exe on Windows machines, and eclipse.app on Macintosh machines.
Now load up eclipse.exe or eclipse.app, whichever is appropriate for your platform.
If you are installing a Windows x64 version then you may run into run-time problems related to insufficient memory and/or insufficient stack size. To correct for this edit the eclipse.ini file and change the following entries:
- Increase XXMaxPermSize to at least 1024M
- Set Xms512m
- Set Xmx1024m
Run the eclipse program. if you encounter an error related to Java machine then you may be trying a 64-bit Eclipse version with a 32-bit Java version or the reverse. Make sure they are compatible. The easiest solution is to install an Eclipse version that matches your Java version.
Make sure everything is running by importing a simple PHP script and selecting run as script. If all is okay, we can move onto the next stage.
If you get an error that complains that it can't find the PHP executable then you need to define its path inside Eclipse as follows:
- Open Windows/Preferences
- Open PHP/PHP Executables
- Click 'Add' and add the path of where your PHP is. If you are using Zend this will be at c:/Zend/ZendServer/bin.
Debugging with the webserver
Now that you can run simple scripts, we can move onto setting up Eclipse for use with a webserver. Follow the steps below:
- Step one involves downloading the server debugger from the Zend site, which requires registration and login. Go to http://www.zend.com/products/studio/downloads, register, and get the "Studio Web Debugger" for your platform and architecture. There are instructions there on how to install this as well, which should be the same as described here. (Note that the old location for this was http://downloads.zend.com/pdt/server-debugger/, which is still referred to on many places on the web. This old location has libraries only up through PHP 5.2, but if that's all you need, will work fine.)
- Check which version of PHP you are running by executing the phpinfo() function.
- Find the appropriate .so or .dll file and copy it to your PHP folder.
- Open php.ini and add the following lines to the bottom of the file.
For Linux, assuming the library is in /usr/lib/php5 as it would most likely be on Debian/Ubuntu:
zend_extension=/usr/lib/php5/ZendDebugger.so zend_debugger.allow_hosts=127.0.0.1 zend_debugger.expose_remotely=always zend_debugger.httpd_uid=-1
zend_extension_ts=/full/path/to/ZendDebugger.dll zend_debugger.allow_hosts=127.0.0.1 zend_debugger.expose_remotely=always zend_debugger.httpd_uid=-1
Make sure you search for any other instances of zend_extension or zend_extension_ts that are in you php.ini file and delete them/comment them out.
- Restart Apache.
- If it worked, running phpinfo() again should now include some stuff about Zend Debugger
Note: You may need to disable "eaccelerator" in your php.ini if it is defined there and it shows up in you phpinfo() listing to avoid debugging issues.
You can either add or set the following line if "eaccelerator" exists:
or just simply comment out the "eaccelerator" lines using a semi-colon (;) in front of each statement.
Don't forget to review your phpinfo() to make sure eaccelerator is disabled.
Create a new project
The next stage is to create a project for your Drupal test site.
- File -> New -> PHP Project
- Type in a memorable project name
- Uncheck 'Use default' under Project contents. This will stop Eclipse from from importing your files, allowing you to work with your project from different programs.
- Browse for the location of your project
- Click the 'Finished' button
You should now have an empty project. The next stage is to import your files:
- Select the menu item File -> Import...
- Select 'File System'
- Click browse next to 'From directory' and search for the folder containing your Drupal project
- Select the files you wish to import (probably all of them)
- Click browse next to 'Into Folder' and select the project you just created
- Click 'Finish'
You've now created a new project!
Run Debugger as Web Service
Once setup, each debug session is a one click operation. But first you need to run through the following steps.
- In menu Run -> Debug... (The Debug window will pop up)
- On the left-hand side of the window is a folding menu. Right click on 'PHP Web Page' and select New.
- Change the name to something memorable. Bear in mind that you will be doing this for each individual site, so make sure the name relates to this specific site.
- In the 'Server' section click the 'New' button. A window will pop up.
- Give it a name such as your site name
- Enter the URL that points to the document root of the server
- Click OK
- In the 'File/Project' section click the 'Browse' button.
- Select the relevant project directory and click OK
- In the 'URL' section, uncheck Auto Generate and type in the URL of your site (i.e. the same URL you would type into your web browser)
- Click the 'Debug' button
If all is well you should now be dubugging your Drupal site! Of course you will need to add a breakpoint for it to work.
Setup for working with Drupal coding standards
Before you can happily work with a Drupal project you will need to configure Eclipse to work with Drupal coding standards.