Setting up your workstation for Joomla! development -- Part 2

From Joomla! Documentation

Note: This is the second of the 2-part article Setting up your workstation for Joomla! development.

Check Out Joomla! Source Code

Now we are going to create a new PHP project that will contain all of the source code files for Joomla!. We can import the source code and create our PHP project at the same time.

Import Project

To start, select File / Import to display the Import screen. Expand the SVN node and select "Checkout Projects from SVN" as shown below.

Press the Next button to display the "Checkout from SVN" screen shown below.

Check the item "Create a new repository location" and press the Next button to display the screen shown below. Enter the location "http://joomlacode.org/svn/joomla/development/releases/1.5", which is the current repository for the Joomla! 1.5 source code. Note, if you wish to create a project based on the 1.6 source code, use the URL "http://joomlacode.org/svn/joomla/development/trunk".

When it asks for the username and password, use "anonymous" as the username and leave the password blank.

Press the Next button. Eclipse will work for a few moments and then display the parent folder and subfolders for this SVN repository, as shown below. Several times during the following process.

Select the top line (the top-level folder) and press Next. Check the option "Check out as a project configured using the New Project Wizard" and in the next dialog enter the project name of "Joomla 1.5 Source", as shown below.

Press the Finish button. The New Project "Select a wizard" dialog will display. Select PHP / PHP Project, as shown below.

Press Next to display the "New PHP Project" wizard screen. Enter the project name, "Joomla 1.5 Source", as shown below.

Press Finish. A warning message will display as shown below.

Press OK. At this point, Eclipse will work for several minutes, downloading all of the Joomla! source code files from the Joomlacode site. You will see a progress bar, as shown below. In the lower right corner you will see a message "SVN Checkout (xx%)", again showing the progress of the checkout.

After a few minutes, the new project will be created, and you should see the familiar folder structure of Joomla!, as shown below.

Run and Install Joomla!

Next, let's run the Joomla! front end from inside Eclipse. The file we need to run is "index.php" in the home directory. Right-click this file and select Run As / PHP Web Page, as shown below.

The first time you do this, the following screen will display showing you the URL that Eclipse is executing. Press OK.

Our default browser opens and runs Joomla!. Since this is the first time we have executed this copy of Joomla!, we are taken to the Joomla! Installation Wizard, as shown below.

Go through the normal installation process. Install the sample website.

Note: This SVN version controlled code has been specially altered so you don't need to (nor would you want to) delete the "installation" folder.

Run Joomla! Back End

To execute the Joomla! back end, navigate to the "administrator/index.php" file and again right-click and select Run As / PHP Web Page. This time we are executing the administrator "index.php" file as shown below.

Press OK and the Joomla! login screen should display.

At this point, we have the complete Joomla! source code synchronized with the Joomla! source repository and we can execute the Joomla! front end and back end from inside Eclipse.

Create a Test Joomla! Patch

Let's create a simple patch file using Eclipse. We're going to add comment lines to two different files and then create a patch that could be (but won't be) used to update the Eclipse SVN repository.

Edit Files

Navigate to the file "components/com_content/views/frontpage/tmpl/default.php" and add a new comment line as shown below.

Save the file (either Ctrl+S or press the Save button in the toolbar).

Now, open the file "components/com_content/views/frontpage/tmpl/default.xml" by double-clicking on it in the PHP Explorer view. Eclipse has an XML editor built in, although you can configure it to use an external editor if you prefer. The XML editor has two tabs at the lower left: Design and Source. The Design tab opens by default. This present a tree structure of the XML file. You can expand any of the trees, as shown below.

Click on the Source tab to display the Source window, as shown below.

Add a new comment line in line 2 as shown below.

You may have noticed that, when you typed the opening comment tag "<!--" , Eclipse automatically added the closing part of the tag for you. Again, save the file.

Now, look at the PHP Explorer view. Notice that we now have little black "*" symbols next to the files and folders that have changes, as shown below.

Create Patch File

Next, select the tmpl file folder in the PHP Explorer view, right click, and select Team / Create Patch, as shown below.

Select "Save in file system" and press Browse to select the file and a new folder for the patch. Notice that Eclipse automatically includes all changed files. If you wanted, you could include only selected files in the patch.

Press Next to show the Advanced Options dialog shown below. Select "Project" for the patch root and press Finish.

The patch file will be created. Open this file with a text editor. It should have the contents as shown below. This file could then be used to apply these changes to an SVN repository.

Index: components/com_content/views/frontpage/tmpl/default.php
===================================================================
--- components/com_content/views/frontpage/tmpl/default.php    (revision 10613)
+++ components/com_content/views/frontpage/tmpl/default.php    (working copy)
@@ -1,4 +1,5 @@
 <?php // no direct access
+// This is a comment to test patch creation.
 defined('_JEXEC') or die('Restricted access'); ?>
 <?php if ($this->params->get('show_page_title', 1)) : ?>
 <div class="componentheading<?php echo $this->params->get('pageclass_sfx') ?>">
Index: components/com_content/views/frontpage/tmpl/default.xml
===================================================================
--- components/com_content/views/frontpage/tmpl/default.xml    (revision 10613)
+++ components/com_content/views/frontpage/tmpl/default.xml    (working copy)
@@ -1,4 +1,5 @@
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Test comment for patch -->
 <metadata>
        <layout title="Frontpage Blog Layout">
                <message>

Undo File Changes

Before we finish, let's look at how we can undo our changes. The easiest way is to just use the Eclipse editor undo command. Go back to the "default.xml" file in the editor. Press Ctrl+Z (or use Edit / Undo Text Change) once or twice until the comment is gone. Save the file. Notice that the black "*" is now gone from this file in the PHP Explorer view.

Now let's look at a more sophisticated way to undo changes. Navigate to the "default.php" file and right-click anywhere inside the edit area. Select Compare With / Base Revision from the context menu. This will display the screen shown below.

This is the Eclipse Text Compare editor. It shows you every change between any two files. In this case it's comparing the base revision we downloaded from the Eclipse repository to the current file, where we added the comment. The second button in the toolbar is called "Copy Current Change From Right to Left". Press this button and now the files will be identical. Press Save to save the changes, and notice that now all of the black "*" have disappeared. This indicates that there are no changes between our files and the this revision in the repository.

Working With Patches

Bug fixes are normally created and tested using patch files. Patch files are plain-text files that tell Subversion how to change one or more source code files to reflect the changes included in the bug fix. A simple patch can be a small change to one file. A large patch might have major changes to multiple files. You can read more about patch files in the article Learn more about patch files.

Note that JBS members do not normally commit changes to the Joomla! SVN. Our job is done when the patch is tested successfully and the issue is change to "Ready to Commit" status. Committing the changes to the Joomla! codebase is done by Ian, Kevin, or a member of the Development Team.

The normal work process for testing a bug fix is as follows:

1. Update your local Joomla! to the latest from the repository. To do this, right-click on the project and select Team / Update.
2. Normally, you will want to test the issue before applying any patch, to make sure you can duplicate the problem.
3. Download the patch file from the tracker and apply the patch. The url is http://joomlacode.org/gf/project/joomla/tracker/ and choose the Joomla! 1.6.x Bug Tracker link
4. Re-test to see if the patch corrects the problem.
5. Update the tracker with your results.
6. Revert the programming changes so that your local SVN repository stays in synch with Joomla!.

How to Apply a Patch

To apply a patch file created by someone else, here are the steps:

1. Download the patch to your local computer (for example from the Joomla! Tracker).

2. Select the project in the PHP Explorer, right-click, and select Team / Apply Patch. The dialog shown below will display:

3. Browse to the desired patch file and press the Next button. The screen will display as shown below:

4. Select the target project where you want to apply the patch. Note that patches should normally be created with the project as the Patch Root. Press Next to display the Review Patch screen shown below:

5. This screen shows you the file or files that will be modified by this patch. If you like, you can double-click on the file name to open the Eclipse compare window for the file. This shows you exactly what the changes to each file will be, as shown below.

6. Press the Finish button to apply the patch. Notice the black "*" symbols in the PHP Explorer, as shown below. These show the files and folders that were modified by the patch and, therefore, are now different than the base SVN repository.

Revert Changes

When you are done testing a patch, normally you will want to undo the patch so your local code base stays in synch with the Joomla! SVN. In Eclipse, you can undo patches in two ways: either revert changes or apply a patch in reverse.

Revert Changes

You can change a file or group of files back to the original state by using the SVN Revert command. In Eclipse, you just highlight the file or folder, right-click, and select Team / Revert. If you have selected one file, this file will be changed back to the version in the SVN repository. If you have selected a folder or project, then all of the files in this folder or project will be reverted. In this case, Eclipse will show a dialog listing all of the files to be reverted. You can then pick which ones you want to revert or cancel the operation.

Reverse a Patch

You can also use Eclipse to undo a patch. Follow the same procedure as for applying a patch. When you get to Review Patch screen, Eclipse will show an error, as shown below. Because the file has already been patched, the starting point of the file does not match what is in the patch file.

If you click on the box "Reverse Patch", as shown below, the error disappears, indicating that the patch will be reversed.

Press the Finish button to complete the process. If you have only applied one patch file to the SVN, then reversing the patch is the same as just reverting the files (Team / Revert). However, if you are working with more than one patch file, the ability to reverse just one patch can be useful.

Debug Joomla! From Eclipse

Let's do a quick debug session in Eclipse.

Set a Breakpoint

First, we'll set a breakpoint inside Joomla!. Go to the PHP Explorer view and find the Joomla! file "components/com_content/views/frontpage/tmpl/default.php" as shown below.

Double-click the file name to open this file for editing. Double-click in the blank area just to the left of line 2, as shown below. A small blue circle will display.

This sets a breakpoint at this line of code. When running in debug mode, Eclipse will suspend the program and we can debug from this point.

Create a Launch Configuration

Now, let's set up what's called a Launch Configuration so we can more easily run the front-end in debug mode. Select the menu Run / Debug Configurations . Select "PHP Web Page" in the left-hand tree list. Right-click and select "New" to display the screen below. Notice that the "Break at First Line" option is checked by default. Keep this setting.

Change the Name to "Debug Front End" and press the Browse button and browse to the "index.php" file in the top-level folder of the Joomla 1.5 Source project, as shown below.

Click OK and Close buttons to save the launch configuration.

You can use this same procedure to create a launch configuration for the Joomla! back end. Just call it "Debug Back End" and browse to the "index.php" file under the administrator folder.

Run a Debug Session

We can select our launch configuration by pressing the drop-down arrow next to the debug icon in the toolbar, as shown below. If our just created launch configuration with the name "Debug Front End" doesn't show up, we have to add it to our favourites by pressing "Organize Favorites..." in the same drop down and adding our launch configuration to the favorite list.

At this point, two things happen. First, a new browser session starts with an empty window. This is because Joomla! is suspended at the first line of code (since we chose "Break at First Line"). Second, inside Eclipse, the PHP Debug perspective is opened automatically for us, showing the line where we are suspended.

Press the Resume button (green right arrow) in the toolbar to take us to the next breakpoint. This time we suspend at line 2 of the "default.php" file, where we set our break point. The screen should look like the one below.

To end the debug session, just press the red Terminate button. Eclipse will again display the PHP perspective and you will get a "teminated" window in your browser.

Since we created a Debug launch configuration, we can re-run the debug session for the front end just by using the Debug drop-down in the toolbar. (Note: If you don't want to worry about launch configurations, you can always just highlight the "index.php" file, right-click, and select Run / Debug As / PHP Web Page. Using launch configurations is just a convenience.) When we launch the debug session, we again go to the PHP Debug perspective.

Now, press the Resume button once to take us to line 2 of "default.php". Press Resume a second time. Now the Joomla! front page displays and the debugger doesn't show any active frames in the debug view. This is because Joomla! is now just waiting for the user to do something.

Press the link "Joomla! Overview". Now the debugger has again stopped at the first line of code (line 15) of "index.php", again because we have the "Break at First Line" option set. Press Resume again, and the "Joomla! Overview" article displays and again we have no active frames in the Debug view.

Let's take a quick look at some other debugger features. Press the "Home" link and press the Resume button once. Again, you should be suspended at line 2 of "default.php", where we set our manual breakpoint.

Press the "Step Over" button in the debug toolbar. The screen should display as shown below, with the current line now being line 3.

Two other "step" buttons are "Step Into" and "Step Return". These are used to navigate down to a called method and navigate back. Let's try them. Notice that line 3 includes a call to the "get" method of the "$this->params" object. Press "Step Into" and now we navigate to this method, as shown below.

This method is defined in the file "libraries/joomla/html/parameter.php" file and is a member of the "JParameter" class (since "$this" was a JParameter object). Notice that the current line also calls a method. Press "Step Into" again and we navigate to the getValue method of the JRegistry class in the "registry.php" file.

As you might guess, the "Step Return" navigates to the line following the "return" statement of the current method. So if we press "Step Return" once we go back to line 121 of "parameter.php" file.

Let's look at two other debugger features. Hover the mouse on the $key variable in line 135. You should see the value of this variable, as shown below.

Look at the Variables view to the right of the Debug view and you can see the current value of all of the variables, as shown below.

Click on the second frame in the Debug view, as shown below.

Notice that the Variables view changes to show the variables for this frame and the edit window now shows the file for this frame. Click on some other frames to get the idea of this. The "frame stack" allows you to see all of the levels of the program and how we got to the current line of code. We can also see the value of variables at each level in the program. When we step into a method, we add a new frame on the top of the stack. When we step return out of a method, the frame for this method is removed and we go back to the previous stack.

Press Step Return and we now go back to the line in "default.php" where we called the "get" method.

Sometimes it is handy to evaluate an entire expression. Highlight the expression on line 5 "$this->escape($this->params->get('page_title'))", being careful to get the entire expression but no extra characters. Right-click and select Watch from the context menu. This expression is now added to the Expressions view and we can see what it evaluates to, as shown below.

You can also type in an expression by right-clicking inside the Expressions view and selecting "Add Watch Expression".

Important Note: There appears to be a bug when you try to launch a debug session with existing Watch Expressions. You get an error "Unexpected termination of script, debugging ended". To avoid this error, just delete all Watch expressions, using the "Remove All Expressions" button in the toolbar, prior to starting a new debug session.

To finish up, delete the Watch expression and press the red Terminate button to stop the debug session.

Eclipse Tips and Tricks

Recommended Eclipse Settings

Here are some additional Eclipse settings and preferences that are recommended.

Eclipse.ini File Settings

When you install Eclipse, it places a file called eclipse.ini in the root folder (where you unzipped the Eclipse archive). This file controls how much memory Eclipse and Java are allowed to use on your PC. By default, these settings are low and do not take advantage of the computer RAM available on most PC's. Editing this file to the values shown below might make Eclipse run substantially faster:

-startup
plugins\org.eclipse.equinox.launcher_1.0.101.R34x_v20080819.jar
-showsplash
org.eclipse.platform
--launcher.XXMaxPermSize
512m
-vmargs
-Xms512m
-Xmx512m

SVN Label Decorators

Navigate to Window / Preferences and select General / Appearance / Label Decorations and make sure the box "SVN" is checked, as shown below. This should be selected by default when Subclipse is installed.

Show Line Numbers

Navigate to Window / Preferences and select Editors / Text Editors. Make sure the box "Show Line Numbers" is checked, as shown below. This should be selected by default.

Show SVN Console

This option will display the Subversion commands in the Eclipse console. Navigate to Window / Preferences and select Team / SVN / Console. Check the box "Show SVN console automatically when command is run" is checked, as shown below. This will not be checked by default.

phpEclipse Browser Preview Defaults

If you are using phpEclipse (not Eclipse PDT or EasyEclipse), navigate to PHP Eclipse Web Development / Browser Preview Defaults and uncheck all options.

Customising Shortcut Keys

If you do a lot of work in Eclipse, it can save you time to make good use of Eclipse shortcut keys. You can customise these keys to work just the way you want. In the example below, we will add a shortcut key for the SVN command "Compare With Base Revision". Here are the steps:

1. Select Window / Preferences / General / Keys to show the screen below. Scroll down to the command "Compare With Local Base Revision" and highlight it.
   
2. Click in the Binding field and press Ctrl+Shift+X, as shown below. In the "When" drop-down list, select "In Dialogs and Windows", as shown below. Notice that the "Conflicts" field is empty. If you pick a shortcut key that is already used in Eclipse, it will show here.
   
3. Press OK.

Now, you can highlight a file and open the Compare With Base Revision editor just by pressing Ctrl+Shift+X. Note that some shortcut keys may conflict with other applications on your system, in which case they will not work correctly in Eclipse.

Eclipse Edit Windows

• You can maximize the edit area in the Eclipse workbench just by double-clicking on the tab for the active window (or by clicking the maximize icon in the upper right corner of the edit area). Double-clicking again restores the edit area.
• You can a second edit window inside the edit area by dragging the active tab to the right-hand edge of the edit area, as shown below.

This will create two edit windows, side by side. You can maximize the entire edit area by double-clicking on the active tab. The workbench will display as shown below, with two edit windows.

To reverse the process, just drag the tab of the right-hand window back to the left window.

Compare With Base Reivsion

When working with patches, it can often be handy to see the changes you have made to a specific file. To do this, right click on any file in your Joomla! project and select Compare With / Base Revision.

If the local version of the file is different than the base revision, the Eclipse Compare Editor will display in the Edit Area of the workbench, as shown below.

Text Compare

You can use the Eclipse text compare to compare two different files or different versions of the same file. To compare two different files:

• Highlight both files in the PHP Explorer view.
• Right-click on one of the files and select Compare With / Each Other. This will open the Text Compare window in the edit area.

You can also compare file that aren't part of an Eclipse project. To do this:

• Create a new file in Eclipse by selecting File / New and the file type (for example, HTML, XML, text, PHP). Select a name for the file and the correct folder in your Eclipse project.
• Open the external file you want to compare and copy the contents to the clipboard.
• Inside the Eclipse editor for the new file, paste the contents and save the file.
• Repeat this procedure for the second file to compare.
• Compare the two files using the Compare With / Each other method outlined earlier.

Local History

Eclipse automatically tracks changes you make to files in the editor and allows you to view and use these prior versions. To see the local history of a file, right-click on the file in the edit window and select Team / Show Local History. This will open the History view as shown below.

Each line is a version of the file at this point in time. With this view, you can:

• Double-click on a line to open the file as it was at that time.
• Right-click on a line and select "Compare Current with Local" to compare the current file version with the version at this time.

Using the Eclipse Text Compare window, you can also revert to the earlier version of the file or just revert some of the changes.

Mouse Hover

If you hover the mouse on a class or method, the PHPDoc information will show in a tooltip, as shown below. You can press F2 to move the focus to this tooltip to allow scrolling.

If you hold down Ctrl and then hover, the source code of the element will display in the tooltip, as shown below. Again, F2 allows you to scroll the tooltip.

The element also becomes a hyperlink. Clicking on the element will open the element's source file for editing.

Back and Forward Buttons

You can navigate back and forward, like in a browser, using the Back and Forward buttons in the Eclipse toolbar, shown below.

These let you navigate to previous files you were editing or viewing. You can also use the drop-down menu to go to a specific file and location, as shown below.

Outline View

This view (by default in the lower left) shows the structure of any classes in the active file. For example, open the file "libraries\joomla\factory.php" for editing. The Outline view will show the methods and fields of the JFactory class, as shown below.

Clicking on a member in the Outline view highlights the declaration of this member in the source file.

PHP Project Outline View

This view displays a list of constants, classes and functions for all files within the selected project. Selecting an element in the PHP Project Outline view will open the source file in the editor.

PHP Functions View

This view shows the most commonly used PHP Classes, Constants and Iterators. You can add a function to a source file by double-clicking the desired function. The function will be added at the current cursor location in the active source file.

Code Assist

Eclipse will attempt to complete common PHP statements and methods for you. Simply type in the first part of the statement and press Ctrl+Space to invoke code assist. For example, open "index.php" for editing and go to line 13. Type "def" and press Ctrl+Space. The screen should display as shown below.

At this point, you can click on any option in the pop-up window to select the desired statement. Click on "defined" and press Enter. The line will now read "defined()". Press Ctrl+Space again and a list of constants will show, as shown below.

You can read more about Code Assist in the "Working with Code Assist" section of the PDT User Guide (PDT User Guide > PDT Help > Getting Started > Basic Tutorials). Code assist is a great feature of Eclipse and can save you a lot of time.

Open PHP Manual

You can access the PHP Manual for any PHP function by highlighting the function name in an edit window or the PHP Functions view and selecting Open PHP Manual. The PHP manual page for this function will display in a browser window.

Other Manuals

Other forms of PHP documentation that you can download are available from php.net. This page includes HTML formats and CHM format.

On Windows, the extended CHM format is the most useful as it includes comments from the live PHP references.

A free viewer for Mac OSX 10.5, iChm, is available from robinlu.com (Chmox and xChm are either not maintained or unreliable enough to use). If you are integrating iChm with Eclipse (either with PDT or phpEclipse) you will need to remember to specify the full path to the actual binary, eg (and adjusting the path for the correct location):

/Applications/iChm/Content/MacOSX/iChm /Users/you/php_manual_en.chm

MySQL manuals are available in a variety of formats from dev.mysql.com.

Filter on Problem Window

If your Problem (or Task) window is not showing you the right problems, you may need to adjust your filter. It can be particularly helpful to adjust the filter to just show the working selection.

To do that click on the down triangle in the upper right corner of the Problem window.

This will display a dropdown menu. Select "Configure Contents". In the "Configure Contents" window, check "Warnings on Selection".

Click "OK".

This screen also gives additional parameters that you could use.

Troubleshooting

Error When Doing Team->Commit

When doing a commit, you get the message "svn: Server sent unexpected return value (501 Method Not Implemented)". This error can be caused by doing an anonymous checkout on a project that requires credentials to commit. The anonymous credentials are cached and so the commit is not authorized. To fix this, you need to clear the SVN cache. This can be done by removing the cache file. For XP, the file is c:\Documents and Settings\[username]\Application Data\subversion\auth\svn.simple. For Vista, it is c:\Users\[username]\AppData\Roaming\subversion\auth\svn.simple.

If you use Tortoise, you can right-click and select SVN->Settings->Saved Data and press the Clear button next to Authentication Data.

Extension Development

For Eclipse setup information related to Joomla! extension development, see Setting up your workstation for extension development.