Introduction: Debug Joomla PHP With Eclipse and LAMP on Ubuntu 16.04

By

The purpose of this Instructable is to setup a LAMP web server on Ubuntu, install a Joomla! Content Management System and finally debug PHP scripts with Eclipse.

A Windows Instructable with XAMPP is located here.

You'll get a quick installation guide in 10 detailed steps. At the end of this Instructable, you're ready to debug your own website. Only freeware software will be used.

Question: Do you need a PHP debugger?
Answer: When you're developing websites in PHP, then the answer is YES.

A debugger can save you a lot of time to find bugs in your PHP scripts, such as Joomla! components, modules or plugins. It allows you to step through the code, set breakpoints, watch variables and many more.

Prerequisites:

  • Ubuntu 16.04 clean installation. (32-bit or 64-bit)
  • At least 2GB free disk space.
  • Internet connection.

Steps:

  1. Install Apache
  2. Install MySQL
  3. Install PHP with phpmyadmin
  4. Configure Apache Xdebug module
  5. Install Joomla
  6. Test Joomla installation
  7. Install Java
  8. Download and configure Eclipse
  9. Create a new PHP project with Eclipse
  10. Basic Eclipse debugging

Several commands should be executed in a terminal. You can open a terminal with the [CTRL+ALT+T] shortcut. (See screenshot) All commands are executed as a normal user, displayed with a $ prompt. For example:

$ whoami

Note: Copy and paste the commands without the $ character and press [ENTER].


I could not find good tutorials on the web, so I decided to share my experiences with you, step by step. The first step is to setup a LAMP web server which stands for: Linux Apache MySQL PHP.


Let's continue and have fun! :-)

Step 1: Install Apache

Install the web server Apache:

$ sudo apt-get install apache2

You can check the Apache installation by opening a web browser at http://localhost. A welcome message "It works!" will be displayed when the installation is successful.


The root directory of the Apache web server is write protected by default:

$ ls -la /var/www/html
total 20
drwxr-xr-x 2 root root  4096 aug  9 20:54 .
drwxr-xr-x 3 root root  4096 aug  9 17:26 ..
-rw-r--r-- 1 root root 11321 aug  9 17:26 index.html

Add your user to the "www-data" group to add write permission:

$ sudo adduser $USER www-data

Logout and login:

$ gnome-session-quit

Change owner to the group "www-data":

$ sudo chown -R www-data:www-data /var/www

Add group write permission:

$ sudo chmod -R g+rwX /var/www

Now you can create a new file as normal user (without sudo):

$ cd /var/www/html
$ touch test.html
$ ls test.html
test.html

Step 2: Install MySQL

Install the MySQL database server:

$ sudo apt-get install mysql-server

During the installation, you'll be asked to set a root password.

Step 3: Install PHP With Phpmyadmin

phpmyadmin is a web based MySQL administration tool which is a powerful tool for web developers. Frequently used operations such as managing databases, tables, columns, relations, indexes, users, permissions, etc can be performed via a web interface.

Installing phpmyadmin will automatically install and configure PHP.

Note: I could not get phpmyadmin up and running when PHP is already installed.


Install phpmyadmin with the command:

$ sudo apt-get install phpmyadmin

During the installation, you'll be asked to configure the web server automatically. Press [SPACE] to select apache2 and press [ENTER]. (Use [TAB] or arrow keys to navigate).

Answer "Configure database for phpmyadmin with dbconfig-common?" with Yes. ([LEFT ARROW], [ENTER])

Enter the MySQL root password.


Install mcrypt for phpmyadmin:

$ sudo apt-get install mcrypt

Restart Apache:

$ sudo service apache2 restart


Check your installed PHP version with the command:

$ php -v
Copyright (c) 1997-2016 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies
    with Zend OPcache v7.0.8-0ubuntu0.16.04.2, Copyright (c) 1999-2016, by Zend Technologies

To check the phpmyadmin installation, open http://localhost/phpmyadmin in your web browser.

Login with user name root and your MySQL phpmyadmin password.

Step 4: Configure Apache Xdebug Module

Xdebug will be used to debug PHP scripts. It should be configured manually in the Apache web server.

Install Xdebug:

$ sudo apt-get install php-xdebug

To find your Apache php.ini configuration file, enter the following command:

$ find /etc/php -name php.ini
/etc/php/7.0/cli/php.ini
/etc/php/7.0/apache2/php.ini

The Apache PHP configuration file on Ubuntu 16.04 is located in
/etc/php/7.0/apache2/php.ini, but depends on the installed PHP version.

Open php.ini in a text editor, for example:

$ sudo gedit /etc/php/7.0/apache2/php.ini

Add the following lines to the end of the file. Then save the file:

[Xdebug]
zend_extension=xdebug.so
xdebug.remote_enable=1
xdebug.remote_port=9000

Restart Apache:

$ sudo service apache2 restart

Check the Xdebug installation which should display " with Xdebug...":

$ php -v
PHP 7.0.8-0ubuntu0.16.04.2 (cli) ( NTS )
Copyright (c) 1997-2016 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies
    with Zend OPcache v7.0.8-0ubuntu0.16.04.2, Copyright (c) 1999-2016, by Zend Technologies
    with Xdebug v2.4.0, Copyright (c) 2002-2016, by Derick Rethans

Create a new info.php file in the Apache web server root directory:

$ gedit /var/www/html/info.php

Add the following lines and save the file:

<?php phpinfo(); ?>

Note: Please refer to Step 1 Install Apache to fix the permission of the /var/www/html directory when you can't save the file.

Now open a web browser at http://localhost/info.php.
A new xdebug configuration should be displayed. (See screenshot)

Step 5: Install Joomla

Now you're ready to install Joomla.

Download Joomla from https://www.joomla.org/download.html.

In my case, it is saved to ~/Downloads/Joomla_3.6.2-Stable-Full_Package.zip.

Extract the zip file in the /var/www/html directory:

$ cd /var/www/html
$ unzip ~/Downloads/Joomla*

Remove the index.html example:

$ rm index.html

Set Apache permission for the Joomla directory:

$ mv htaccess.txt .htaccess

Set user and group "www-data" permission:

$ sudo chown -R www-data:www-data /var/www

Add group write permission:

$ sudo chmod -R g+rwX /var/www

Open http://localhost in a web browser to start the Joomla installation.

Set Main Configuration:

  • Site Name
  • Description
  • Administrator Email
  • Administrator Username
  • Administrator Password
  • ConfirmAdministrator Password

Click Next

Set Database Configuration:

  • Database Type: MySQLi
  • Host Name: localhost
  • Username: root
  • Password
  • Database Name: joomla
  • Table Prefix: jos_
  • Database Process: Remove

Click Next

Finalization:

Make sure Pre-Installation Check column is green.
Check the /var/www/html permission above when configuration.php Writable is set to No.

Click Install

Congratulations! Joomla! is now installed.

Click Remove installation folder

Step 6: Test Joomla Installation

Open http://localhost in a web browser.
Login with your user name and password.

Open http://localhost/administrator to login in the back-end for administrative purposes.

Step 7: Install Java

Java is required to run Eclipse.

Add the following PPA (Personal Package Archives) to install Oracle Java 8 which includes JDK8 and JRE8:

$ sudo add-apt-repository ppa:webupd8team/java
$ sudo apt-get update
$ sudo apt-get install oracle-java8-installer

Note: You must agree with the license agreement by selecting: <Yes>.
[LEFT ARROW], [ENTER]

Check the Java installation, for example:

$ java -version
java version "1.8.0_101"
Java(TM) SE Runtime Environment (build 1.8.0_101-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.101-b13, mixed mode)

Step 8: Download and Configure Eclipse

Download Eclipse PDT (PHP Development Tools) from:
https://eclipse.org/pdt/#download > Download 32 bit or 64 bit version.

To check if you're using Ubuntu 32 or 64 bit:

$ uname -i
x86      < This is 32 bit
x86_64   < This is 64 bit

Extract the eclipse-php-neon-R-linux-gtk-x86_64.tar.gz file:

$ cd ~/Downloads
$ tar -zxvf eclipse-php*

Start Eclipse:

$ cd eclipse
$ ./eclipse

Accept default workspace and click OK.

Close the Welcome tab (by clicking the X).

Click in the toolbar Window > Preferences:

  • Click PHP > Interpreter:
    This should be set to your PHP version.
  • Click PHP > PHP Executables > Add:
    • PHP executable tab:
      • Name: PHP
      • Executable path: /usr/bin/php
      • PHP ini file (optional): /etc/php/7.0/apache2/php.ini
      • SAPI type: CLI
    • Click Next:
      • Debugger: XDebug
      • Port: 9000

Click Finish > OK.

Step 9: Create a New PHP Project With Eclipse

Now we're ready to create and configure a new PHP project and use existing Joomla sources.

Click in the toolbar: File > New > PHP project:

  • Project name: joomla
  • Check: Create project at existing location (from existing source)
  • Directory: /var/www/html

Click Finish.

Click in the toolbar Window > Preferences > Servers >
Select Default PHP Web Server > Click Edit:

  • Click Server tab:
    • Server Name: Default PHP Web Server
    • Base URL: http://localhost
    • Document Root: /var/www/html
  • Click Debugger tab:
    • Debugger: XDebug
    • Port: 9000
  • Click PathMapping tab > Add:

Click OK > Finish > OK.

Let's continue to debug your fist Joomla PHP project!

Step 10: Basic Eclipse Debugging

Now you're ready to start debugging.

  1. Expand the joomla project directory.
  2. Double click index.php to open it in the editor.
  3. Set a breakpoint on line 12 (left of the line number).
  4. Click in the toolbar debug button (small down arrow) >
    Debug As > PHP Web Application.
    Next time you can click the Debug button in the toolbar instead.

Set Launch URL to: http://localhost/index.php > click OK.

You'll be asked to switch to Debug perspective. Answer with Yes. You can switch back to PHP project perspective by clicking the small PHP button in the upper right corner.

Your default web browser such as Firefox will be opened at: http://localhost/index.php. You can change this for example to Chrome in the Preferences dialog box > General > Web Browser.

The web browser displays a blank white page, because the breakpoint in Eclipse should be reached on index.php line 12.

Now you should be able to step through the code with shortcuts:

  • [F5] Step into
  • [F6] Step over
  • [F7] Step return (or out)
  • [F8] Resume (or continue)

Now press 3x [F6].

The $startTime variable is displayed in the Variables tab. Hover over the variable to see the contents of the variable.

Press [F8] to resume. The entire website is now displayed in your web browser.

Refresh your web page in the web browser to reload the page. The breakpoint in index.php line 12 is reached again.

Notes:

  • Use the debug button to start a debug session once.
  • Use the terminate button [CTRL]+[F2] to stop the debugger.

Step 11: Finally

Congratulations! Now you're completely up and running when you reached this final step.

Feedback is welcome.
Please leave a message when this tutorial was helpful for you.

Thanks!