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
- How to run joomla through eclipse
- Install joomla on your desktop
- Install Eclipse with PHP plugin
- Install joomla into eclipse
- Set the required project settings
- Amend the httpd.conf file
- Install dbg Debugger PHP module
- Amend the PHP ini files
- Test the debgugger has been installed correctly
- Begin debugging
Part 1 - How to get your existing joomla site onto your desktop
Joomla on the desktop
Install XAMPP
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
Include joomla in XAMPP apache config
Making configuration changes
Configuration.php changes
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';
Database setup changes
....
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
<?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
Batch file to start mysql
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
"...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
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
Install joomla on your desktop
Install Eclipse with PHP plugin
The eclipse platform itself...
Eclipse 3.1.2 (win32) (Section: "Platform Runtime Binary")
and the PHP plug in
PHPeclipse 1.1.8 (win32)
Install joomla into eclipse
Set the required project settings
Amend the httpd.conf file
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.Alias /eclipse "c:/eclipse/workspace/"
<Directory "c:/eclipse/workspace/">
Options Indexes MultiViews
AllowOverride None
Order allow,deny
Allow from all
</Directory>
Install dbg Debugger PHP module
DBG Debugger dbg-2.11.32-win32-php5.zip
Amend the PHP ini files
C:\xampp\apache\bin\php.ini
C:\xampp\php\php5.ini
; 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"
Test the debgugger has been installed correctly
<?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
<?php
$msg = "Hello World";
print $msg;
?>
- 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.