Debugging Joomla in eclipse

by John McGeechan

 Synopsis

On occasion it is may be useful to be able to step through the Joomla core code at run-time. This may be for general debugging or in order to better understand the internal plumbings of Joomla.

This article shows how to set up an Apache server in windows to run on your desktop and how to set up the eclipse development environment and how to debug the joomla core....


NB Since originally writing this article the eclipse PDT platform has been born. This is a PHP centric development tool which includes a debugger. This provides pretty much everything that this article covers.

However, I have left this article in circulation as I still get mails about it.


 

 

Part 1 - How to get your existing joomla site onto your desktop

Part 2 - How to run and debug joomla through Eclipse


 

Part 1 - How to get your existing joomla site onto your desktop

Joomla on the desktop

An explanation of how to replicate your existing joomla site from a remote server onto your Windows desktop.

Install XAMPP

First things first. Let's install xampp (NB For a fuller explanation of this , see http://www.plog4u.org/index.php/Using_PHPEclipse:Installation:XAMPP_Example_Installation)

XAMPP is a very useful piece of software, download at

http://prdownloads.sourceforge.net/xampp/xampp-win32-1.4.9.zip?download

XAMPP runs a local apache server, mysql server as well as perl and PHP interpreters (hence XAMPP).
  • Download XAMPP version 1.4.9
  • do not download the installer version, juts the zip files
  • extract zip files directly to c: (you should end up with c:\xampp)
  • go to c:\xampp and execute apache_start.bat* then mysql_start.bat*
  • if everthing is working OK you should see an xampp splash page at "http://simplersolutions.biz". You now have a local server. Hurrah !
  • to stop the server, go to c:\xampp and execute apache_stop.bat* then mysql_stop.bat*

* NB Avoid using the xampp_start.exe and xampp_end.exe to start and stop the servers. Because although it appears to invoke the apache_start.bat and mysql_start.bat scripts it doesn't. Any changes that you may make to individual .bat files (see Creating Mysql batch files), are simply ignored by these 2 exes.

The docroot for the server (ie http://simplersolutions.biz) is at c:\xampp\htdocs). To run stuff on the local server you have two choices. Either place files directly on the docroot ie at c:\xampp\htdocs, or run your files from their usual location, but use a HTTP alias in the C:\xampp\apache\conf\httpd.conf in order to tell XAMPP where it can find your stuff. See Amending the apache alias file for an explanantion.

Copy remote joomla site

Download the joomla site files from the remote server directly to your hard drive (use FTP). Install to say C:\joomla.

Include joomla in XAMPP apache config

Ensure the XAMPP apache and Mysql servers are running. Open your browser at simplersolutions.biz http://simplersolutions.biz/joomla. You should see a page not found error. This is correct, due to the fact that apache knows nothing about this file. Stop the XAMPP apache and mysql servers. Add a completely new alias as described in Amending the apache alias file for your joomla directory. Restart the servers, reload the page in your browser. You should hopefully see a PHP error. Why ? Because the configuration.php file is still using the settings as held on your remote server (and the chances of them being the same on your local are so unlikely I am going to explain what you need to do anyway !). Stop the servers again.

Making configuration changes

Ther are two types of change required, changes to joomla configuration files and database changes. One is easy, one is a little trickier.

Configuration.php changes

NB The following assumes that joomla was copied to C:\joomla, if it is anywhere else amend the following instructions accordingly.
Amend the joomla/configuration.php file as follows...
  • $mosConfig_absolute_path = 'C:\joomla';
  • $mosConfig_cachepath = 'C:\joomla\cache';
  • $mosConfig_live_site = 'http://simplersolutions.biz/joomla';
Restart the servers, reload the browser, this time you should see something. You should in fact get the nicely formatted joomla page that instructs you to contact your administrator.

Database setup changes

The reason you have got the 'contact your adminstrator' page, is due to database mismatch issues. It gets a bit bumpy from here, so buckle your seatbelts. First things first. Have you exported your joomla MySql database from your remote server ? If not, do so now (use sqldump on your remote server and FTP the file to your desktop). We will wait here for you....
....
time passes
....
Right the database now needs to be imported onto your local SQL server. And it needs to have the same name as the $mosConfig_db field in the configuration.php file. Xampp has admin tools for doing this (look in xampp/mysql/bin) and if you are hapy to use these tools then so much the better as this will result in your database being stored in xampp/mysql/data, which will then be consistent with the xampp server as it is started up by the mysql_start/stop batch files. However, you may already have your own sql set up, which you want to stick with. In my case I had several databases already on my local machine that I administer via the mysql suite of tools (Mysql server, Mysql administrator and Mysql browser). I used these tools to import the database, but this means that the data ends up residing in (in my instance) C:\Program Files\MySQL\MySQL Server 5.0\data and not c:/xampp/mysql/data. This is important as it means that you are opting not to use the XAMPP Mysql Server, which is perfectly acceptable, but does mean that some new Mysql .bat files will be required. Panic ye not as setting up these batch files aint no biggy (see Creating Mysql batch files). OK, so now you have your database installed. But still we are not quite there. The user details still need to be set up. The user and password as defined by the fields $mosConfig_user,$mosConfig_password in the configuration.php need to be identical to those in the database. Use your preferred SQL admin client in order to create this user in your newly created database. Ensure that this user has all of the required access rights to the database.

Other potential database problems

If you have ensured that the database has been imported and that the user has been created in that database and that the user details are identical to those values held in the confiuration.php. Then stop and restart the servers and go to http://simplersolutions.biz/joomla if you still get the formatted page that tells you to contact your administrator, then there is still a mismatch somewhere. To see what this mismatch might be. Create the following test.php file in your joomla directory....

<?php

include_once('configuration.php');

$link = @mysql_connect( $mosConfig_host, $mosConfig_user, $mosConfig_password );

if (!$link) {
print('Could not connect: ' . mysql_error());
}
else {
print 'Connected successfully';
};
?>

Load http://simplersolutions.biz/joomla/test.php in your browser and this should give you the diagnostics you need to sort out the problem. If the problem is the following .....

Could not connect: Client does not support authentication protocol requested by server; consider upgrading MySQL client

The most likely reason for this is because joomla stores passwords (in confirguration.php) in an MD5 hashed format. Later versions of the client recognise this format and do a translation, earlier versions do not. The absoloute simplest way to solve this problem is to clear the password for the user (ie the user has no password). Do this in the database and in the $mosConfig_password field in the configuration.php. Hopefully, this should do the trick. If you are not happy to have no password for the user then consider upgrading your client. Assuming you solve all SQL problems via the test.php screen (you may have to stop and start all servers several times), then theoretically the front page of your joomla site at http://simplersolutions.biz/joomla should be visible and voila a fully functioning joomla website on your desktop.

Once the novelty of seeing your joomla site has worn off , you may want to try running joomla through the eclipse platform ( How to run joomla through eclipse), I believe that this is truely the holy grail for serious joomla developers. Through this mechanism you can see the internal workings of joomla by stepping through the code or - and more usefully - you can use it to debug tricky component and module problems.

Creating Mysql batch files

This section is only important if you do not wish to use the xampp Mysql server, then it is time to create your own Mysql batch files for starting and stopping the server.

Batch file to start mysql

You can call this anything you like, so long as you always use this to start the server. Something like mysql_start.bat would suffice. Open a text editor and add the following lines

echo have overriden xammps SQL so that it runs my preferred server
"...your preferred Mysql server path.../bin/mysqld.exe" --defaults-extra-file="...your preferred server path.../my.ini" --standalone

Note that it you have used your chosen server on a previous occasion then the settings in my.ini should all be set up correctly. If not, then this begs the question why are you not simply using the XAMPP Mysql server ?

Batch file to stop mysql

You can call this anything you like, so long as you always use this to stop the server. Something like mysql_stop.bat would suffice. Open a text editor and add the following lines

"...your preferred server path.../bin/mysqladmin" shutdown -u rootusername

NB !!!! in my particular case I assigned no passsword to my root user. Why ? Because it means that I can run these batch files and not have to worry about being prompted for any passwords, so it becomes a simple case of clicking a link on my desktop to start/stop the server. For me this is not a problem as I am the only one running software on my desktop. If this is a problem for you then you will need to start and stop the server manually each time.To do this, issue the following command through a DOS shell

"...your preferred Mysql server path.../bin/mysqld.exe" --defaults-extra-file="...your preferred server path.../my.ini" --standalone -u rootusername -p

or

"...root to your mysql server..../bin/mysqladmin" shutdown -u rootusername -p

Amending the Apache alias file

A quick explanantion on how to acess a file from anywhere on your local machine, via the simplersolutions.biz

To set up an HTTP alias relative to the docroot, you need to edit the apache config file httpd.conf (in c:\xampp\apache\conf). Add the following alias somwehere in the file (preferably with the other aliases)

Alias /foobar "c:/path/to/yourdir"
<Directory "c:/path/to/yourdir">
Options Indexes MultiViews
AllowOverride None
Order allow,deny
Allow from all
</Directory>

Then, if you had something like c:/path/to/yourdir/xxx.html, to access this on the local host open the following address in your browser ...

http://simplersolutions.biz/foobar/xxx.html

NB If you make any changes to the config be sure to stop and restart the apache server....

 

Part 2 - How to run and debug joomla through Eclipse

How to run joomla through eclipse

A very good explanation of this can be found here, but in brief...

Install joomla on your desktop

First, ensure that joomla runs OK on your desktop (for a full explanantion of how to do this, see Joomla on the desktop).

Install Eclipse with PHP plugin

Hopefully you should have at least heard of eclipse (If not, I am not sure what you are doing here). A big problem with installing Eclipse and the PHP plugin, is ensuring that you have compatable versions. The best stable versions that are also compatabile are ...

The eclipse platform itself...
Eclipse 3.1.2 (win32) (Section: "Platform Runtime Binary")

and the PHP plug in
PHPeclipse 1.1.8 (win32)

Download Eclipse and install into say c:\eclipse. Download PHP eclipse,unzip it and copy the plugins folder contents , but not the actual plugins folder itself - you do not want a nested plugins/plugins hierarchy ! - into the c:\eclipse\plugins folder. Start up eclipse via the desktop shortcut or through c:\eclipse\eclipse.exe. When promted set the default workspace to C:\eclipse\workspace.

Install joomla into eclipse

If you followed the steps in "Part 1 - How to get your existing joomla site onto your desktop" then joomla should already be installed on the hard drive. The next step is to create a new eclipse project called 'joomla' (or frankly whatever you want). Then, in the eclipse navigator window, right click on the project and 'import' all the joomla files from their current hard drive location. Joomla is now installed within eclipse.

Set the required project settings

Right click on the joomla project for the project properties window. Click on 'PHP Project settings' and set 'use workspace settings' radio button. Click the 'Configure Workspace settings', set the simplersolutions.biz to 'http://simplersolutions.biz/' and set 'DocumentRoot' to C:\eclipse\workspace.

Amend the httpd.conf file

See Amending the apache alias file on how to do this. You will need to point to the eclipse workspace eg

Alias /eclipse "c:/eclipse/workspace/"
<Directory "c:/eclipse/workspace/">
Options Indexes MultiViews
AllowOverride None
Order allow,deny
Allow from all
</Directory>

Stop and restart the apache server. Open your browser and navigate to http://simplersolutions.biz/eclipse/joomla to then see joomla as it appears in the eclipse workspace. Note how this address is completely different to http://simplersolutions.biz/joomla, this is the joomla site now imported into eclipse. Also, start up eclipse and open the index.php page and also open the php browser (WIndow > Show View > PHP browser), the front page of the joomla site should now be displayed within the eclipse browser (this assumes Apache and Mysql servers have both been stopped and restarted !). A few more things are still required however in order to use the debugger.

Install dbg Debugger PHP module

Download the following version of the debugger...

DBG Debugger dbg-2.11.32-win32-php5.zip

Note that this zip file has several versions, each corresponding to a different PHP version. The required file is php_dbg.d11-5.02. Copy this file to c:\xampp\php\extensions and c:\xampp\php\ext and immediately rename it to php_dbg.d11

Amend the PHP ini files

Some amendments have to be made to the PHP ini files held in

C:\xampp\apache\bin\php.ini
C:\xampp\php\php5.ini

Modify these 2 files accordingly...
; this is to see output while debugging
implicit_flush = On

; check this parameter
extension_dir = c:\xampp\php\ext\

; add the dbg extension (only if it doesnt already exist)
extension=php_dbg.dll

; add to the end of the file
[debugger]
debugger.enabled=on
debugger.profiler_enabled=on
debugger.ports=7869
debugger.JIT_host = clienthost
debugger.JIT_port = 7869

[Zend]
zend_extension_ts = zend_extension_ts = "C:\xampp\php\ext\php_dbg.dll"

 

Note, all zend entries should be commented out if they exist, except for the zend_extension_ts. stop and restart apache.

Test the debgugger has been installed correctly

To quickly see if the debugger has been installed properly create the following file testDebug.php in c:\xampp\htdocs ...

 

<?php
print phpinfo();
?>

Load http://simplersolutions.biz/testDebug.php in your browser. If the debugger has been successfully installed, you should see some reference to the dbg debugger somewhere in this page.

Begin debugging

Before you start trying to run joomla's index.php through the debugger (indeed, if you ever even want to) try debugging a simpler program. Start eclipse and open the joomla project. Start the PHP browser (Window > show view > PHP Browser). Create a new file "temp.php", add the following code to the file.
<?php
$msg = "Hello World";
print $msg;
?>

 

On saving the file, the program should appear in the PHP browser window...
  • Double-click the gutter to the left of the line numbers in the PHP file editor to create a breakpoint. A blue dot should now appear, this is the breakpoint.
  • Open the debug perspective Window->Open Perspective->Debug.
  • Go to the menu Run->Debug. Choose PHP DBG Script as the Configuration
  • Enter a new name for this configuration eg Test
  • switch to the File tab, use browse and find the file temp.php
  • Switch to the php Environment tab, Choose the Interpreter tab, select an existing interpreter from the list or create a new one (for example c:\php\php.exe )
  • choose the Remote Debug sub-tab and check the Remote Debug option note that the Remote Sourcepath is the absolute path to the Eclipse project eg C:\eclipse\workspace.
  • Click Debug to start debugging session and then Switch back to the Eclipse Debug Perspective window.
If the debugger stops on the breakpoint and shows variable values in the variable view, then volia, you are now debugging. IF not , double check that you have Set the required project settings
If you do have a problem, you can try emailing me at info@simplersolutions.biz , I cannot guarantee a response, but you never know