Configuring Eclipse and Xdebug

From Joomla! Documentation

Configure XDebug[edit]

Note: Getting XDebug to work on some workstations can be difficult. XDebug is NOT required to be able to use Eclipse for PHP development. If you are new to Eclipse for PHP, you can skip this section and use Eclipse without XDebug if desired. You can install XDebug later if you need it.

Edit XDebug Eclipse Settings[edit]

The first thing we need to do is to tell Eclipse to use the XDebug we installed earlier. Navigate to Window / Preferences, as shown below. (Mac users: Eclipse / Preferences...)

Window preferences menu.png


This will open the Preferences dialog. Expand the PHP node on the left and select "Debug" to display the screen below.

Debug preferences.png

Notice that the "Break at first line" box is checked. This means that the debugger will always break or suspend execution at the first line of code. We'll see this later on when we run the debugger.

Select XDebug for the PHP Debugger. You might get the message below.

Debug port message.png

If so, just ignore it and press OK. (We're going to change the ports now anyway.)

In order to ensure compatability with php.ini, press the "Configure" link for the PHP Debugger to display the screen below.

Installed debuggers.png

Highlight the XDebug line and press Configure to display the screen below.

Xdebug port.png

Change the port number to "10000" as shown, to match what we put in the "php.ini" file earlier. (I also changed the port number for the Zend debugger to "10001" just to get rid of the port 9000 warning message.)

On some systems, you may get Javascript errors like the following:

A Runtime Error has occurred. Do you wish to Debug? Line: 1 Error: Syntax error

If so, you can eliminate these messages by changing the "Output Capture Settings / Capture stdout" from "copy" to "off".

Set Debug Options[edit]

Next, we need to set some options. Select the menu Window / Preferences to open the Preferences dialog. Expand PHP and Debug and select "Workbench Options", as shown below.

Workbench options.png

Change the settings as shown above. You can experiment with these settings to make Eclipse best for you.

Next, select the "PHP Servers" item on the tree to display the screen shown below.

Php servers.png


Select the "Default PHP Web Server" (the only one in the list) and press the Edit button to display the Edit Server dialog shown below.

Edit server.png

Recall that we created our workspace, called "joomla_development", under the "c:\xampp\htdocs" directory. So the URLs to the HTML and PHP files in our project will need to include the "joomla_development" directory name (for example, "http://localhost/joomla_development/Test Project/test.php"). If we change this here, Eclipse will create the URLs for us automatically. So complete the screen as shown above and press OK.

Test XDebug[edit]

Now we finally get to have some fun. We're going to write a simple PHP script and run and debug it to test that Eclipse is set up correctly. If you are already familiar with Eclipse, you can just skip over this section. If not, we'll go through some basics.

Debug a PHP File[edit]

Now, let's try debugging this script. Again, select the "test.php" file and right-click, but this time select "Debug As / PHP Web Page", as shown below.

Debug as web page.png

This time, the browser opens and suspends. (Note: If Eclipse does not suspend at the first line, try closing Eclipse and re-starting it.)

Go back to Eclipse and open the PHP Debug perspective by selecting Window / Open Perspective / PHP Debug, as shown below.

Open debug perspective.png

This opens the Debug Perspective, with the "test.php" file suspended, as shown below.

Debug perspective.png

Recall from earlier that the "Break at first line" option was selected. This is why the debugger has suspended here, on the first line in our program.

There is a lot going on in this screen. The Debug view in the upper left shows the "frame" information. In this case, we are suspended on line 2. The editor window is now in the middle of the screen. A small blue arrow shows where the program is suspended.

In the upper right is the Variables view. This shows the variables that are in scope at this point in the program.

The toolbar in the Debug perspective is important. The tools are labeled below.

Debug toolbar.png

  • Resume: Resume execution until the next breakpoint or until the program is finished.
  • Terminate: Terminate the debug session. It is important to always terminate the session before trying to run a new session. This must be done even if the browser is closed.
  • Step Into: Used to step into a called function.
  • Step Over: Used to step to the next line.

If you are familiar with debuggers from other IDEs, these commands will probably be familiar. If not, you can read more about it in the Eclipse help documentation and experiment on your own.

To finish, let's press the Step Over button. The Debug view and editor now show that we are on line 3. Note that this means that we are about to execute line 3. Also, note the change in the Variables view. Now the variable $mytest has a value of "this is a test" because line 2 has now executed.

Press Step Over again. Now we're on line 4. Look at the browser window. It should now say "this is a test", since now line 3 has executed. Press Step Over again and look at the browser window. Now it shows the output of "phpinfo()".

Finally, press Resume. Notice that the program is no longer suspended and the browser no longer shows that it is waiting to complete the page. The script has completed, but our debugger session is still running.

To close the debugger, select the "Remote Launch" in the Debug view and press the Terminate button. Two things happen. In the browser, a new window launches showing a terminate message. In Eclipse, the PHP perspective automatically displays. This is because we set this in the Debug preferences.

Now we had to manually open the Debug perspective, which is an extra step. We can tell Eclipse to do this automatically for us. We just go to Window / Preferences / Run/Debug / Perspectives, select "PHP Web Page", and check "Always" for "Open the associated perspective when launching", as shown below.

Php debug preferences.png

At this point, the XDebug is working correctly in Eclipse.

Troubleshooting Tips[edit]

Debugger Doesn't Stop at Breakpoint[edit]

This can happen if another application is using the port you chose for XDebug. If you experience this problem, try changing the port from 10000 to 10002 or some other value. You have to change the port number in your php.ini file as well as in the Eclipse preferences. You also have to re-start your Apache server to make the change effective.

See also: Configuring XDebug for PHP development

Debug Joomla! From Eclipse[edit]

Let's do a quick debug session in Eclipse.

Set a Breakpoint[edit]

First, we'll set a breakpoint inside Joomla!. Go to the PHP Explorer view and find the Joomla! file "components/com_content/views/frontpage/tmpl/default.php" as shown below.

Default php file.png

Double-click the file name to open this file for editing. Double-click in the blank area just to the left of line 2, as shown below. A small blue circle will display.

Breakpoint example.png

This sets a breakpoint at this line of code. When running in debug mode, Eclipse will suspend the program and we can debug from this point.

Create a Launch Configuration[edit]

Now, let's set up what's called a Launch Configuration so we can more easily run the front-end in debug mode. Select the menu Run / Debug Configurations . Select "PHP Web Page" in the left-hand tree list. Right-click and select "New" to display the screen below. Notice that the "Break at First Line" option is checked by default. Keep this setting.

Debug run dialog.png

Change the Name to "Debug Front End" and press the Browse button and browse to the "index.php" file in the top-level folder of the Joomla 1.5 Source project, as shown below.

Select index file.png

Click OK and Close buttons to save the launch configuration.

You can use this same procedure to create a launch configuration for the Joomla! back end. Just call it "Debug Back End" and browse to the "index.php" file under the administrator folder.

Run a Debug Session[edit]

We can select our launch configuration by pressing the drop-down arrow next to the debug icon in the toolbar, as shown below. If our just created launch configuration with the name "Debug Front End" doesn't show up, we have to add it to our favourites by pressing "Organize Favorites..." in the same drop down and adding our launch configuration to the favorite list.

Debug dropdown.png

At this point, two things happen. First, a new browser session starts with an empty window. This is because Joomla! is suspended at the first line of code (since we chose "Break at First Line"). Second, inside Eclipse, the PHP Debug perspective is opened automatically for us, showing the line where we are suspended.

Press the Resume button (green right arrow) in the toolbar to take us to the next breakpoint. This time we suspend at line 2 of the "default.php" file, where we set our break point. The screen should look like the one below.

Joomla debug screenshot.png

To end the debug session, just press the red Terminate button. Eclipse will again display the PHP perspective and you will get a "teminated" window in your browser.

Since we created a Debug launch configuration, we can re-run the debug session for the front end just by using the Debug drop-down in the toolbar. (Note: If you don't want to worry about launch configurations, you can always just highlight the "index.php" file, right-click, and select Run / Debug As / PHP Web Page. Using launch configurations is just a convenience.) When we launch the debug session, we again go to the PHP Debug perspective.

Now, press the Resume button once to take us to line 2 of "default.php". Press Resume a second time. Now the Joomla! front page displays and the debugger doesn't show any active frames in the debug view. This is because Joomla! is now just waiting for the user to do something.

Press the link "Joomla! Overview". Now the debugger has again stopped at the first line of code (line 15) of "index.php", again because we have the "Break at First Line" option set. Press Resume again, and the "Joomla! Overview" article displays and again we have no active frames in the Debug view.

Let's take a quick look at some other debugger features. Press the "Home" link and press the Resume button once. Again, you should be suspended at line 2 of "default.php", where we set our manual breakpoint.

Press the "Step Over" button in the debug toolbar. The screen should display as shown below, with the current line now being line 3.

Debug stepover.png

Two other "step" buttons are "Step Into" and "Step Return". These are used to navigate down to a called method and navigate back. Let's try them. Notice that line 3 includes a call to the "get" method of the "$this->params" object. Press "Step Into" and now we navigate to this method, as shown below.

Params get method.png

This method is defined in the file "libraries/joomla/html/parameter.php" file and is a member of the "JParameter" class (since "$this" was a JParameter object). Notice that the current line also calls a method. Press "Step Into" again and we navigate to the getValue method of the JRegistry class in the "registry.php" file.

As you might guess, the "Step Return" navigates to the line following the "return" statement of the current method. So if we press "Step Return" once we go back to line 121 of "parameter.php" file.

Let's look at two other debugger features. Hover the mouse on the $key variable in line 135. You should see the value of this variable, as shown below.

Variable hover.png

Look at the Variables view to the right of the Debug view and you can see the current value of all of the variables, as shown below.

Variables view.png

Click on the second frame in the Debug view, as shown below.

Change frame.png

Notice that the Variables view changes to show the variables for this frame and the edit window now shows the file for this frame. Click on some other frames to get the idea of this. The "frame stack" allows you to see all of the levels of the program and how we got to the current line of code. We can also see the value of variables at each level in the program. When we step into a method, we add a new frame on the top of the stack. When we step return out of a method, the frame for this method is removed and we go back to the previous stack.

Press Step Return and we now go back to the line in "default.php" where we called the "get" method.

Sometimes it is handy to evaluate an entire expression. Highlight the expression on line 5 "$this->escape($this->params->get('page_title'))", being careful to get the entire expression but no extra characters. Right-click and select Watch from the context menu. This expression is now added to the Expressions view and we can see what it evaluates to, as shown below.

Expressions view.png

You can also type in an expression by right-clicking inside the Expressions view and selecting "Add Watch Expression".

Important Note: There appears to be a bug when you try to launch a debug session with existing Watch Expressions. You get an error "Unexpected termination of script, debugging ended". To avoid this error, just delete all Watch expressions, using the "Remove All Expressions" button in the toolbar, prior to starting a new debug session.

(Above solution did not work in my case but to not show superglobals was the solution. - User:Rolandd)

To finish up, delete the Watch expression and press the red Terminate button to stop the debug session.