Setting up your workstation for Joomla! development

From Joomla! Documentation

Note: This article has been updated as of January 2009 to reflect the new Eclipse PDT version 2.0 and XAMPP version 1.7, which now includes the XDebug program. This makes installation simpler. Note, if you have Eclipse PDT version 1.0 installed with XDebug, just install Eclipse PDT 2.0 in a new folder and point to your existing workspace.

Introduction

This article provides detailed instructions for setting up your workstation for Joomla! development. Note that there are many possible configurations for doing Joomla! development. Any environment that supports Apache, MySql, PHP, and Subversion should work for writing Joomla! code and extensions.

This document provides step-by-step instructions for setting up and working with the Eclipse IDE. The example used and screenshots are for Windows XP, but the basic steps are the same for Linux.

Install XAMPP

XAMPP is an easy-to-install package that bundles the Apache web server, PHP, XDEBUG, and the MySql database. This allows you to create the environment you need to run Joomla! on your local machine. The latest version of XAMPP is available at the XAMPP web site. Downloads are available for Linux, Windows, Mac OS X and Solaris. Download the package for your platform.

Important Note Regarding XAMPP and Skype: Apache and Skype both use port 80 as an alternative for incoming connections. If you use Skype, go into the Tools-Options-Advanced-Connection panel and deselect the "Use 80 and 443 as alternatives for incoming connections" option. If Apache starts as a service, it will take 80 before Skype starts and you will not see a problem. But, to be safe, disable the option in Skype.

Installation on Windows

Installation for Windows is very simple. You can use the XAMPP installer executable (for example, "xampp-win32-1.7.0-installer.exe"). Detailed installation instructions for Windows are available here.

For Windows, it is recommended to install XAMPP in "c:\xampp" (not in "c:\program files"). If you do this, your Joomla! (and any other local web site folders) will go into the folder "c:\xampp\htdocs". (By convention, all web content goes under the "htdocs" folder.)

If you have multiple http servers (like IIS) you can change the xampp listening port. In <xamppDir>\apache\conf\httpd.conf, modify the line Listen 80 to Listen [portnumber] (ex: "Listen 8080").

Installation on Linux

Download the latest version available at the XAMPP web site. After downloading simply type in:

 sudo tar xvfz xampp-linux-1.7.1.tar.gz -C /opt

To start XAMPP simply execute the command:

 sudo /opt/lampp/lampp start

The XAMPP package for Linux does not includes the XDebug PHP debugger. To install XDebug on Debian or Ubuntu:

- Install the build-essential package:

sudo apt-get update
sudo apt-get install build-essential
sudo apt-get install autoconf

- Download the development package for your version of XAMPP and extract it over your existing installation:

sudo tar xvfz xampp-linux-devel-1.7.1.tar.gz -C /opt

- Build XDebug:

wget http://xdebug.org/files/xdebug-2.0.4.tgz
tar xzf xdebug-2.0.4.tgz
cd xdebug-2.0.4/
/opt/lampp/bin/phpize

After this you will have following output on your console…

Configuring for:
PHP Api Version:         20041225
Zend Module Api No:      20060613
Zend Extension Api No:   220060519

./configure --with-php-config=/opt/lampp/bin/php-config
make
sudo make install

Then the output will be this.. please monitor the directory specified.

Installing shared extensions:     /opt/lampp/lib/php/extensions/no-debug-non-zts-20060613/

Create a folder in your temp folder that will holds the data file generated by XDebug:

sudo mkdir /opt/lampp/tmp/xdebug
sudo chmod a+rwx -R /opt/lampp/tmp/xdebug

Test XAMPP Installation

Once XAMPP is installed, you can test it by opening your browser and navigating to "http://localhost". You should see the XAMPP welcome screen similar to the one below.

Select the link called "phpinfo()" in the left-hand menu. This will display a long screen of information about the PHP configuration, as shown below.

At this point, XAMPP is installed successfully. Notice the "Loaded Configuration File" which is highlighted in the screenshot above. We will be editing this file in the next section to configure XDebug.

Edit PHP.INI File

For Windows

Starting with version 1.7, XAMPP includes the XDebug PHP debugger, but it needs to be configured for use. To do that, we will edit the "php.ini" file to configure XDebug. The "Loaded Configuration File" in the screenshot above tells you what "php.ini" file is being used. For Windows, this is normally "c:\xampp\apache\bin\php.ini".

Important note for Windows Vista users: As of April 2009 (XAMPP version 1.7.0), the file "php_xdebug.dll" that is included with XAMPP does not work with Windows Vista. The symptom of this problem is that the Apache server will stop if this version of XDebug is loaded. To correct this problem, download XDebug version "Xdebug 2.0.0 / 5.2 VC6" from the XDebug website. This will download a file called php_xdebug-2.0.0-5.2.2.dll. Save this file in the extensions folder (for example, c:\xampp\php\ext) and change the php.ini file to point to this file, as shown below. With this file, XDebug works correctly with Vista, including 64-bit.

We need to edit this file to configure XDebug as follows:

Find the line "implicit_flush" and set it as follows:
```
implicit_flush = On
```
Find the section called "[Zend]" and comment out all of the lines by putting a semi-colon (";") at the start of each line.
Find the "[XDebug]" section and uncomment out all of the lines (except for the first comment line). For Windows, it should look like the example below:

[XDebug]
;; Only Zend OR (!) XDebug
zend_extension_ts="C:\xampp\php\ext\php_xdebug.dll"
xdebug.remote_enable=true
xdebug.remote_host=localhost
xdebug.remote_port=10000
xdebug.remote_handler=dbgp
xdebug.profiler_enable=1
xdebug.profiler_output_dir="C:\xampp\tmp"

For Windows Vista, you will use the file downloaded from the XDebug site. So the first line will be

zend_extension_ts="C:\xampp\php\ext\php_xdebug-2.0.0-5.2.2.dll"

For Linux

We will edit the "php.ini" file to configure XDebug. The "Loaded Configuration File" in the screenshot above tells you what "php.ini" file is being used. For Linux, it will be something like "/opt/lampp/etc/php.ini".

We need to edit this file to configure XDebug as follows:

Find the line "implicit_flush" and set it as follows:
```
implicit_flush = On
```
Add the following lines at the end:

;xDebug Configuration starts

zend_extension = /opt/lampp/lib/php/extensions/no-debug-non-zts-20060613/xdebug.so

xdebug.profiler_output_dir = "/tmp/xdebug/"
xdebug.profiler_enable = On
xdebug.remote_enable=On
xdebug.remote_host="localhost"
xdebug.remote_port=10000
xdebug.remote_handler="dbgp"

;xDebug Configuration ends

Test XDebug Installation

Now, we need to check that XDebug is installed correctly. To do this, we need to re-start XAMPP. In Windows, we can just browse to the "c:\xampp" folder in Windows Explorer and double-click the program "xampp-control.exe" to open the application shown below.

Press the "Stop" button for "Apache". The button with then read "Start". Press "Start" for Apache and wait a few seconds and the green "Running" message will again display. Then press "Exit" to close the application.

In Windows, if you get "ERROR: MySQL service not started [-1]", you may be able to correct this by going to c:\xampp\mysql and running mysql_uninstallservice.bat followed by mysql_installservice.bat.

In Linux, to restart XAMPP execute the command

 sudo /opt/lampp/lampp restart

Once XAMPP has been restarted, open a browser and navigate to "http://localhost" to display the XAMPP welcome message. Press the "phpinfo()" link again to display the PHP information screen. Scroll down to the lower part of the screen. You should see a section for "XDebug" as shown below.

Look at the settings you entered in the "php.ini" file above. You should see these same settings in the xdebug display, as shown below.

At this point, XDebug is set up correctly.

Install Eclipse

Install Java

Eclipse is written in Java, so before you can install Eclipse, you need to make sure you have a recent version of Java running. Note that many Linux distributions include third-party Java runtimes (or JVM's for "Java Virtual Machine"), some of which don't work with Eclipse. The safest thing is to make sure you are running the Sun JRE (Jave Runtime Environment). You can download the latest Java version at www.java.com. If you already have a recent version of the Sun JRE (for example, 1.5 or 1.6), you can skip this step.

Download Eclipse

The next step is to download Eclipse. The easiest thing is to install the Eclipse PDT (PHP Development Tools) "all-in-one" bundle. This is available here. There are downloads for Windows, Linux, and Mac OS X. When you download, you will be asked to pick a download mirror. At the time of this writing, the name of the Windows download is "pdt-all-in-one-S20080601_RC2-win32.zip" and is 122mb.

Installing Eclipse is very easy -- you just unzip the file to a target directory. In Windows, it is best to use a third-party "zip" program to do the unzipping. In some cases, Windows Explorer will not correctly unzip this archive and Eclipse won't run correctly. I use

I created a directory called "c:\eclipse_php" for the target. When the file is extracted, you will see a folder called "eclipse" and under that folder 5 folders and six files.

Eclipse will use the default Java JVM for your system. In Windows, this is normally the right one (from Sun). In some Linux distributions, the default JVM may be a third-party program that doesn't work correctly with Eclipse. In this case, you can specify the JVM to use by editing the eclipse.ini file in the eclipse folder as as follows, substituting the correct path to your installed Sun version of the Java JVM:

-showsplash
org.eclipse.platform
--launcher.XXMaxPermSize
512M
-vm
/usr/lib/jvm/java-1.5.0-sun/jre/bin/java
-vmargs
-Xms512m
-Xmx512m

Note that the path to the JVM goes on the line below the "-vm". Also note that the file ends with a blank line.

At this point, you should be able to start up Eclipse. Just find the "eclipse.exe" file inside the eclipse folder and double-click to execute it. In Linux: /path/to/your/eclipse/folder/eclipse

Alternative (Easy) Installation

An alternative way to install Eclipse with the phpEclipse environment is to use EasyEclipse for PHP. This includes everything you need (including Subclipse) in one simple install for most platforms. The following instructions are not applicable for EasyEclipse for PHP.

Create an Eclipse Workspace

The first time you launch Eclipse, the screen below displays.

Before we can start using Eclipse, we need to create a workspace. This is the folder where all of the Eclipse files and project information will be stored. Since we will be working on web-based projects, we want our project PHP and HTML files to be visible to XAMPP. So we will create our workspace in the "c:\xampp\htdocs" folder (in linux: "/opt/lampp/htdocs").

To do this, press the Browse button, navigate to the "c:\xampp\htdocs" or "/opt/lampp/htdocs" folder, and press the New Folder button. Create a directory called something like "joomla_development" and make sure it says the same thing in the Folder field. (You can click on a different folder and then click on the new folder to get the name in the Folder field.) The screen should look like the one below.

Press OK. Then we go back to the Workspace Launcher, as shown below.

Before pressing OK, you can check the box so that you won't need to go through this screen each time you start Eclipse.

Now you should see a splash screen and then a "Welcome to Eclipse" screen, as shown below.

Close this window and the normal Eclipse workbench will display, as shown below.

At this point, Eclipse is installed.

Configure Eclipse

Configure XDebug

The first thing we need to do is to tell Eclipse to use the XDebug we installed earlier. Navigate to Window / Preferences, as shown below.

This will open the Preferences dialog. Expand the PHP node on the left and select "Debug" to display the screen below.

Notice that the "Break at first line" box is checked. This means that the debugger will always break or suspend execution at the first line of code. We'll see this later on when we run the debugger.

Select XDebug for the PHP Debugger. You might get the message below.

If so, just ignore it and press OK. (We're going to change the ports now anyway.)

In order to ensure compatability with php.ini, press the "Configure" link for the PHP Debugger to display the screen below.

Highlight the XDebug line and press Configure to display the screen below.

Change the port number to "10000" as shown, to match what we put in the "php.ini" file earlier. (I also changed the port number for the Zend debugger to "10001" just to get rid of the port 9000 warning message.)

On some systems, you may get Javascript errors like the following:

A Runtime Error has occurred. Do you wish to Debug? Line: 1 Error: Syntax error

If so, you can eliminate these messages by changing the "Output Capture Settings / Capture stdout" from "copy" to "off".

Set Debug Options

Next, we need to set some options. Select the menu Window / Preferences to open the Preferences dialog. Expand PHP and Debug and select "Workbench Options", as shown below.

Change the settings as shown above. You can experiment with these settings to make Eclipse best for you.

Next, select the "PHP Servers" item on the tree to display the screen shown below.

Select the "Default PHP Web Server" (the only one in the list) and press the Edit button to display the Edit Server dialog shown below.

Recall that we created our workspace, called "joomla_development", under the "c:\xampp\htdocs" directory. So the URLs to the HTML and PHP files in our project will need to include the "joomla_development" directory name (for example, "http://localhost/joomla_development/Test Project/test.php"). If we change this here, Eclipse will create the URLs for us automatically. So complete the screen as shown above and press OK.

Set Newline Character (Windows Only)

Let's do one final configuration setting, which only applies if you are running Windows. As you may know, Windows and Linux use different characters to terminate lines in text files. Since the Joomla! source code repository is on a Linux machine, we need to tell Eclipse to create Linux-style patch files. To so this, we'll navigate to Window / Preferences and expand the General tree and select "Workspace". The screen below will display.

Make two changes. Select Other / UTF-8 for the Text file encoding and Other / Unix for the New text file line delimiter, as shown above. Press OK.

At this point, Eclipse is set up and we can start working with PHP files.

Test XDebug

Now we finally get to have some fun. We're going to write a simple PHP script and run and debug it to test that Eclipse is set up correctly. If you are already familiar with Eclipse, you can just skip over this section. If not, we'll go through some basics.

Eclipse Terminology

First, some quick Eclipse terminology. In Eclipse, we talk about the workbench, perspectives, and views. The workbench is just the whole screen. It has an edit area, where we will edit our PHP files, and a series of views around the outside. A view is an area that displays information about a file or some other resource. A perspective is just a pre-packaged layout of views designed for a specific purpose. When we're writing PHP programs, two perspectives are of interest: the PHP perspective and the PHP Debug perspective.

Let's open the PHP perspective. We can select Window / Open Perspective / PHP, as shown below.

Now the workbench displays a different set of views, including the PHP Explorer, in the upper left, and three views in the lower left. Note that Eclipse has pretty good Help, which you can access by pressing F1 or selecting Help / Help Contents from the menu. The screen below shows some of the contents available, including Getting Started, Basic Tutorials, and other useful information.

Create a Project

Remember that we created a workspace when we launched Eclipse. Before we can write any code, we need to create a project. A project stores a group of related program files. For example, the entire Joomla! application will be one project. We're going to create a test project that we can use to test our setup. We'll select the menu File / New / PHP Project, as shown below.

This will open the first screen in the new project wizard, shown below. Enter the project name, in this case "Test Debug", and press Finish.

Our new project will now show in the PHP Explorer view.

Create and Run a PHP File

Next, we need to create a PHP file. Select the "Test Debug" project, right click, select New / PHP File, as shown below.

Press the Browse button and select the "Test Project" for the source folder. The New PHP File wizard will display, as shown below. Enter "test.php" for the file name, and press Finish.

An empty PHP file will now display in the editor. Enter the code shown below, and press the Save button in the upper left toolbar to save the "test.php" file.

Now, we're going to execute the script. We'll select the file "test.php" and right-click and select Run As / PHP Web Page, as shown below.

The script will be run in your default browser, and should display as shown below.

If your php files are set by default to open in a text editor, you may get an error. If so, go to Window/Preferences/General/Web Browser and explicitly select your preferred option.

Note that the "phpinfo()" command displays information about your PHP configuration. This is the same screen we saw earlier, when we clicked on the "phpinfo()" link in the XAMPP home page.

Debug a PHP File

Now, let's try debugging this script. Again, select the "test.php" file and right-click, but this time select "Debug As / PHP Web Page", as shown below.

This time, the browser opens and suspends. (Note: If Eclipse does not suspend at the first line, try closing Eclipse and re-starting it.)

Go back to Eclipse and open the PHP Debug perspective by selecting Window / Open Perspective / PHP Debug, as shown below.

This opens the Debug Perspective, with the "test.php" file suspended, as shown below.

Recall from earlier that the "Break at first line" option was selected. This is why the debugger has suspended here, on the first line in our program.

There is a lot going on in this screen. The Debug view in the upper left shows the "frame" information. In this case, we are suspended on line 2. The editor window is now in the middle of the screen. A small blue arrow shows where the program is suspended.

In the upper right is the Variables view. This shows the variables that are in scope at this point in the program.

The toolbar in the Debug perspective is important. The tools are labeled below.

Resume: Resume execution until the next breakpoint or until the program is finished.
Terminate: Terminate the debug session. It is important to always terminate the session before trying to run a new session. This must be done even if the browser is closed.
Step Into: Used to step into a called function.
Step Over: Used to step to the next line.

If you are familiar with debuggers from other IDEs, these commands will probably be familiar. If not, you can read more about it in the Eclipse help documentation and experiment on your own.

To finish, let's press the Step Over button. The Debug view and editor now show that we are on line 3. Note that this means that we are about to execute line 3. Also, note the change in the Variables view. Now the variable $mytest has a value of "this is a test" because line 2 has now executed.

Press Step Over again. Now we're on line 4. Look at the browser window. It should now say "this is a test", since now line 3 has executed. Press Step Over again and look at the browser window. Now it shows the output of "phpinfo()".

Finally, press Resume. Notice that the program is no longer suspended and the browser no longer shows that it is waiting to complete the page. The script has completed, but our debugger session is still running.

To close the debugger, select the "Remote Launch" in the Debug view and press the Terminate button. Two things happen. In the browser, a new window launches showing a terminate message. In Eclipse, the PHP perspective automatically displays. This is because we set this in the Debug preferences.

Now we had to manually open the Debug perspective, which is an extra step. We can tell Eclipse to do this automatically for us. We just go to Window / Preferences / Run/Debug / Perspectives, select "PHP Web Page", and check "Always" for "Open the associated perspective when launching", as shown below.

At this point, the XDebug is working correctly in Eclipse.

Install Eclipse Subversion

Before we can start coding in Joomla!, we need to be able to work with the Subversion (SVN) source code repository. Subversion is a third-party plugin for Eclipse, so we need to use the Eclipse Update Manager to install it. To do this, navigate to Help / Software Updates, as shown below.

The Software Updates and Add-ons dialog will display. Select the "Available Software" tab. The list of available update sites will display. Press the "Add Site" button to display the Add Site dialog. Enter "http://subclipse.tigris.org/update_1.6.x" as the URL, as shown below.

Press OK and the "Available Software" tab should again display, this time with additional options from the Subclipse site. Select all Subclipse options as shown below. Then press the "Install" button.

Eclipse will work for a minute and then display the Install window, shown below. Press the "Next" button. A "Review Licenses" window appears. Click "I accept the terms of the license agreements". Now click finish.

After the files have been downloaded and installed, Eclipse will show the message below recommending that you restart Eclipse. Press "Yes" and Eclipse will restart.

Once Eclipse has restarted, we can test that the Subversion plugin is working. Select File / Import as shown below.

Then expand the SVN element in the tree. You should see an option called "Checkout Projects from SVN", as shown below.

At this point, the plugin has been installed successfully. Press "Cancel" to cancel the import. (We'll import the Joomla! project in the next section.)