Setting up your workstation for Joomla! development
From Joomla! Documentation
Revision as of 11:07, 10 August 2012 by E-builds
This article or section is in the process of an expansion or major restructuring. You are welcome to assist in its construction by editing it as well. If this article or section
- 1 Introduction
- 2 Install & configure XAMPP, php, Eclipse
- 3 Check Out Joomla! Source Code
- 4 Create a Test Joomla! Patch
- 5 Working With Patches
- 6 Troubleshooting
- 7 Extension Development
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 Apache, PHP, xdebug, Subversion. This instruction uses Eclipse IDE from chapter 4 and onwards. Please refer to the following links for other development tools:
The example used and screenshots are for Windows XP, but the basic steps are the same for Linux.
Install & configure XAMPP, php, Eclipse
- Configuring a XAMPP server for joomla development
- Edit PHP.INI File
- Configuring Eclipse for joomla development
- Installing Subverson on Eclipse 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.
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/trunk" for the 1.6+ 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.
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. A patch file usually has the following naming convention: <issue #>.patch (for example: 12345.patch). If more than one patch file exists, it will be 12345a.patch, 12345b.patch, etc. 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 (Joomla! Bug Squad) 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:
- Update your local Joomla! to the latest from the repository. To do this, right-click on the project and select Team / Update.
- Normally, you will want to test the issue before applying any patch, to make sure you can duplicate the problem.
- 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 Issue Tracker link.
- Re-test to see if the patch corrects the problem.
- Update the tracker with your results.
- 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.
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.
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.
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
- If you use Tortoise, you can right-click and select SVN->Settings->Saved Data and press the Clear button next to Authentication Data.
For Eclipse setup information related to Joomla! extension development, see Setting up your workstation for extension development.