Debugging PHP with Eclipse PDT: A WordPress Example

Introduction

Background

Example

Requirements

• Apache server
• PHP
• Eclipse Luna

Setup

Xdebug

To install XDebug in an Ubuntu-based distribution, run the following command in your CLI:
`sudo apt-get install php5-xdebug`

This installs the xdebug extension in the default php extensions directory, setting it enabled by default.

In Windows, I like to use Xampp. After installing it, Xdebug is pre-configured in the php.ini file.  To enable Xdebug, remove the semicolon ( ; ) to uncomment the line that manages the setup and settings.

zend_extension = "C:\xampp\php\ext\php_xdebug.dll"
xdebug.remote_enable = true

Eclipse

1. Create a new project using the location of the current WordPress location.
2. Click the Debug drop down arrow and select Debug Configurations.
   
3. Select PHP Web Application and click New_configuration. The following window displays:
   
4. On the Server tab click Configure to edit the default server or New to create a new server.  Enter the following information:
   Name—Type a name for the server.
   Debugger—Select XDebug.
   Base URL—Type the URL for your local domain test.
   Local Web Root—Set the path of your web root.
   
   Here are what my settings look like:
   
5. Click OK and return to the Server tab on the Debug Configurations window.
6. Select the PHP file to debug (the file from which the program starts).
7. Configure the URL:
   Note: I configured my virtual domain ( ‘portal’ ) to load content in C:\Users\Octavio\git\wordpress, so I had to disable Auto Generate and remove ‘wordpress’ from the path.
8. Click the Debugger tab and make sure XDebug is selected as the Server Debugger. Optionally, you can set a breakpoint at the first line of code.
   
9. Click Apply to save your changes.

Debug

Now you have configured XDebug. To get started debugging, open the debug configuration profile you just set up and click Debug. The first time you run the debugger, you get an alert to confirm switching to the Debug Perspective. If you checked the Break at First Line option, your app suspends at the first instruction in the index.php file:


Click the Stop button if you want to stop debugging:


Now, follow these steps to debug something basic but useful.

1. In a fresh installation of WordPress add the following code to the functions.php file of current theme:
   

   add_filter( 'the_content', 'my_filter_content_func' );
   
   function my_filter_content_func( $content ) {
     $words_replace = array('wordpress');
     $content = str_ireplace( $words_replace, 'MyBlog', $content );
     return $content;
   }

2. Set a breakpoint on the first line of the function and a second breakpoint on the last line (return $content;).
3. Click Debug and notice that execution stops at the first breakpoint. Also note that we have access to the program variables, in this case the important one is $content.
   
4. Click Resume or press F8 to continue the program execution.  The program execution now stops on the second breakpoint.
   Notice the $content var has changed due to our function’s logic. In some cases, there are too many variables for the Variables tab to be helpful.  In these situations, use the Expressions tab and add only the variables you want to inspect:
   

Bottlenecks

Add a profile to a script

1. Add the following to the php.ini file:
   

   xdebug.profiler_output_dir="/home/admin/traces" 
   xdebug.profiler_append=On
   xdebug.profiler_output_name="%R-%u.trace"
   xdebug.trace_options=1
   xdebug.collect_params=4
   xdebug.collect_return=1
   xdebug.profiler_enable=On

   Details
   xdebug.profiler_output_dir—The path where the profiles are saved.
   xdebug.profiler_append—If On, adds the data at the end of the file instead of replacing last profile.
   xdebug.profiler_output_name—Specifies the profiler’s name
   xdebug.trace_options—If 1, appends the traces instead of overwriting.
   xdebug.collect_params—Specifies if we want to consider the parameters in functions. We use 4 for a full variable contents and variable name. See more options. 
   xdebug.collect_return—If 1, XDebug writes the returning value of functions calls to the trace files.
   xdebug.profiler_enable—If On, enables profiler.

2. Make sure Apache has read and write permissions to the profile’s directory.
3. Webgrind is a web-app that shows the data saved with Xdebug. Download Webgrind and install under /
4. Modify the config.php file with our profiler directory:
   `$profilerDir =”/home/admin/traces/”;`
5. Open Webgrind in a browser:
   

Conclusion