Configuring Xdebug for PHP development/Linux

From Joomla! Documentation

< Configuring Xdebug for PHP development

Theses instructions should work fine on any Debian based distribution such as Debian, Ubuntu, LinuxMint, Xubuntu, Kbuntu and others.


There are several ways to download and install Xdebug to your Linux box, you can do it from your software center, terminal or manual download.

Method 1: From a Linux repository

A Tip!

This is the recommended method because you will get updates and security patches automatically.

Option 1: Terminal

  • Open your terminal and type
 sudo apt-get install php5-xdebug 
  • Wait until the installation process finish

Option 2: Software center

  • Open the software center that comes with your distribution
  • Type in the search box "Eclipse IDE"
  • Select "Eclipse IDE" in the search result list
  • Click on the "install" button
  • Wait until installation processes finish

Method 2: From a downloaded copy

  • Visit this page here and download the most recent version available
  • Do a double click on the downloaded file, your package manager should do the rest of the work automatically

Configuring Xdebug

Open your terminal and type:

sudo gedit /etc/php5/mods-available/xdebug.ini

If the file is empty try this location:

sudo gedit /etc/php5/conf.d/xdebug.ini

That command should open the text editor with the Xdebug configuration file.

At the end of the file content append the following text:





Save changes and close the editor.

In your terminal, type:

sudo service apache2 restart

Note: You can set a different port number if you need to.

Configuring Eclipse IDE

  • Open Eclipse IDE.
  • On Eclipse go to: Toolbar  Window  Preferences  PHP  Debug
  • Find the option: "PHP Debugger" and set it to "Xdebug"
  • On Eclipse go to: Toolbar  Window  Preferences  PHP  Debug  Installed Debugger
  • In the list make sure the port the "Xdebug" option is set to the value "9000"
  • Save changes.

Note: You can set a different port number if necessary.

When you debug a PHP project, Xdebug stops the code execution of the current page and Eclipse IDE by default pops out a perspective with 2 views containing the internal Eclipse IDE web browser and a view with the current HTML output. If you don't like the internal web browser, you can use any other external web browser installed in your computer, such as Google Chrome, Chromium, Firefox and so on.

To set up a different web browser, follow these steps. If you are okay with the Eclipse internal browser, skip this part.

  • On Eclipse, go to: Toolbar  Window  Preferences  General  Web Browser
  • Make sure the option "Use external browser" is selected.
  • If your preferred browser is on the list, select it and save changes. Skip the rest of this part.
  • If your preferred browser is not on the list, press the button "New"
  • Set a name for your new browser, that is "chrome".
  • Set the location of your new browser, that is "/usr/bin/google-chrome"
  • If you don't know the location of the browser, open a terminal and use the command "whereis browsername" to display the browser location. Note: Replace browsername with the name of your preferred browser, that is "whereis google-chrome". Copy one of the locations if there is more than one.
  • Save all changes.

Testing Xdebug and Eclipse IDE

To test our new debugging tool, we need to create an Eclipse PHP project, set the debug configuration for our project and write a few lines of PHP code. This example assumes 3 things:

  1. You understand the Eclipse IDE concepts of "workspace" and "projects". If not, please read this article: Configuring Eclipse IDE for PHP development/Linux#Understanding the folder structure
  2. You already have a working web server. If not, please read this article: Configuring a LAMPP server for PHP development/Linux desktop
  3. Your Eclipse workspace is located at the server's web root folder.

Configuring the workspace

  • If your current workspace is located at your server's web root, skip this part.
  • Open Eclipse IDE.
  • On Eclipse, go to: Toolbar  File  Switch  Workspace  Other
  • Press the button "browse" and browse to the location of your server's web root folder. For example, "/home/youruser/lamp/public_html/"
  • Press "OK" and wait until Eclipse IDE restarts and load the new workspace.

Configuring the test project

  • On Eclipse go to: Toolbar  File  New  Other  PHP  PHP Project
  • Set the project name to "xdebug-test" or anything you like.
  • Press "Ok" to continue.
  • After this Eclipse IDE will automatically create a project folder like this "/home/youruser/lamp/public_html/xdebug-test/". Also you should be able to visualize the new project at the Eclipse IDE Project Explorer view or Navigation view.
  • On Eclipse go to: Toolbar  File  New  Other  PHP  PHP File
  • Set the file name to "index.php".
  • Press "Ok" to continue.
  • After this Eclipse IDE will automatically create a PHP file like this "/home/youruser/lamp/public_html/xdebug-test/index.php". Also you should be able to visualize the new file at the Eclipse IDE Project Explorer view or Navigation view.
  • Find the new "index.php" file at the Eclipse IDE project explorer and open it by double clicking on it.
  • Place the following content to that file:
    $X = 5;
    $X = 8;
    $Y = 2;
    $Z = $X + $Y;
    $Z = $Z + 1;
    echo "Z value is: " . $Z;
Z value is: 11

Configuring the test project debug information

  • On Eclipse, go to: Toolbar  Run  Debug configuration...
  • On the left list, find "PHP Web Application" and do a double click on it to create a new configuration element.
  • Select the new configuration element to display its contents.
  • Set the name to "xdebug-test" or anything you like.
  • Make sure the option "Server debugger" is set to "Xdebug".
  • Make sure the option "Break at first Line" is not checked.
  • In the option "File" press the button "Browse". Find your project "xdebug-test" and expand its contents. Then find and select the file "index.php".
  • Make sure that option URL looks something like this "http://localhost/xdebug-test/index.php"
  • Press "Apply" and "Close" to save changes and continue.

Debugging the test project

As you can see, our "index.php" file has several lines of code. With the debugger, we can study how those lines of code are executed one by one. To stop the execution, we need to set something called "Breakpoint". A Breakpoint is a "mark" in our lines of code that indicate to the debugger to stop the execution and poll the var values. To set a Breakpoint on our code and test the debugger, follow these simple steps.

  • Open the "index.php" of our test project.
  • Locate the line of code "$X = 8;" and do a click on it to place the blinking cursor there.
  • On Eclipse go to: Toolbar  Run  Toggle Breakpoint. You can also used the hotkey "shift+ctrl+B" or simply do a double click on the line number of the line of code at the left side of your editor to toggle a Breakpoint.
  • When a Breakpoint is set, you should see it represented as a little circle next to the line number at the left side of your editor.

Now is the time to execute our project to see how the debugger helps us.

  • On Eclipse, go to: Toolbar  Run  Debug. You can also used the hotkey "F11" or simply do a click in the "little bug icon" located at the second toolbar from the top.
  • Eclipse will open the configured web browser and change to the "Debug perspective". The debug perspective contains a set of pre-configured views useful to do debugging tasks. Among them we have:
    • Debug view: It displays buttons to control the current running debug session. This view contains the current call stack.
    • Breakpoint view: display all your set breakpoints on any project file.
    • Variables view: It's basically a "var dump" of all the PHP variables of your actual session. This view lets you easily navigate through any variable and child members of those variables.
    • Expressions view: here you can set custom expressions, for instance, "$X+$Y+$Z" and see the outcome of each expression without changing the code.
    • Internal browser view and output view: optional if you not configured an external browser, Eclipse IDE will display this view with the current page and the current page HTML output.
  • At this point our web page should look stopped and most likely the browser will show a blank page "waiting" to load the rest of it.
  • Note that the current breakpoint has a "little arrow" over the circle and the line of code is highlighted. This indicates the next line of code to be executed, also know as the "current step".
  • If you take a look at the "variables view", the current value of "$X" should be "5".
  • Go to the "Debug view" and press the button "step over" or use the hotkey "F6" to go one step forward in the code execution.
  • Take another look at the "variables view". The current value of "$X" should be now "8".
  • This way you can neatly study how your code and values changes step by step. You can also hover your mouse pointer over the variables names in the editor. Eclipse will pop up the current values.
  • Keep going forward until the end of the lines of code. At that point the web browser should display the final web page output.