How To Debug PHP In Eclipse On Windows

In this tutorial, we will discuss the terms specific to debugging and the steps required to debug PHP programs using Eclipse IDE for PHP on Windows 10. It assumes that both Java and PHP are already installed on the system.

Notes: You may follow How To Install PHP 7 On Windows or How To Install PHP 8 On Windows to install the most recent version of PHP 7 or PHP 8. The other relevant tutorials include How To Install Java 11 On Windows, How To Install Java 15 On Windows, How To Install OpenJDK 15 On Windows, How To Install WampServer on Windows, How To Install XAMPP On Windows 10, How To Install XAMPP With PHP 8 On Windows 10, and How To Install Eclipse for PHP on Windows.

Also, this tutorial provides all the steps required to debug PHP using Xdebug 3.

You can also follow NetBeans tutorials at How To Debug PHP In NetBeans On Windows, How To Remote Debug PHP Web Apps In NetBeans On Windows, and How To Debug PHP Web Apps In NetBeans On Windows.

Debugging Terms

This section explains all the major terms specific to debugging. These are listed below.

Current Instruction Pointer - The instruction pointer pointing to the current statement where the debugger is paused and waiting for the next instructions.

Breakpoint - The program execution pauses at the breakpoint until further instructions are not provided by the debugger. The breakpoints are added intentionally to check the program for possible errors.

Step Into - Move to the next statement in case there is no function call or enter the function to debug it in case there is a function call on the current statement. We can step into the function called on the current statement to further check it. The execution will pause at the first statement of the function.

Step Out or Step Return - Execute the remaining statements of the function completely and move out of the function and set the instruction pointer on the statement next to the function call.

Step Over - Execute the current statement without going into the function if it's there. It skips the function and executes it without entering into it.

Resume - Resume the execution as the program executes normally till the next breakpoint encounters. The program execution will pause at the next breakpoint if there is any.

Pause - Pause the current execution. The instruction pointer will point to the statement where the execution pause.

Stop - Terminate the current execution of the program and clear the variables stack and breakpoints from memory.

Install PHP

Install the most recent version of PHP by following How To Install PHP 7 On Windows, How To Install PHP 8 On Windows, or How To Install WampServer on Windows.

Install Eclipse for PHP

Next, install the most recent version of Eclipse for PHP by following How To Install Eclipse for PHP on Windows.

Hello World

Write the HelloWorld PHP program in Eclipse by following How To Install Eclipse for PHP on Windows.

Configure Eclipse for PHP and Xdebug

In cases where PHP is installed independently from WampServer or XAMPP, you must create your own php.ini using the php.ini-development or php.ini-production in the PHP installation directory. Also, configure the extensions directory in the php.ini file as shown below.

# Extensions Directory
extension_dir = "<path to PHP installation>\ext"

# Example
extension_dir = "E:\tools\php\php-7.4.16\ext"

Use the Xdebug link to check whether it's already installed and activated for PHP. Write a simple PHP program having the below-mentioned code to get the details about PHP.

// Prints PHP info on Console
phpinfo();

Now execute and copy the content from the console and paste it on the Xdebug site as shown in Fig 1.

Fig 1

Click the Analyse my phpinfo() output Button. It shows that xDebug is not installed on my system and also provided instructions to install the same as shown in Fig 2. 

Fig 2

Move the downloaded DLL file to the ext directory of PHP installation. Note the php.ini location specified by Xdebug. In case you have executed the PHP script to get the output of the phpinfo() function using Eclipse, it might show the location as the temp directory since Eclipse creates the php.ini in temp directories using the php.ini file configured for the installed PHP. You must always configure the correct php.ini file (as shown in Fig 4) instead of the one available in the temp directory as mentioned in the instructions from Xdebug.

Make sure that you have added the zend_extension dll path at the end of the php.ini file. I have added the below-mentioned line at the end of my php.ini file as instructed by Xdebug.

.....
.....
[ffi]
; FFI API restriction. Possible values:
; "preload" - enabled in CLI scripts and preloaded files (default)
; "false"   - always disabled
; "true"    - always enabled
;ffi.enable=preload

; List of headers files to preload, wildcard patterns allowed.
;ffi.preload=

zend_extension = E:\tools\php\php-7.4.16\ext\php_xdebug-3.0.3-7.4-vc15-x86_64.dll

xdebug.mode = debug

Note that I have provided additional configuration i.e. xdebug.mode to configure Xdebug 3. The eclipse will keep waiting for a connection in case we do not configure the xdebug mode.

Install Xdebug following the instructions and open the Preferences Dialog following Windows -> Preferences -> PHP -> Installed PHPs. It shows the installed PHPs as shown in Fig 3.

Fig 3

The Preferences Dialog shows the currently installed PHPs. If it does not show any PHP version, you can always add your own by clicking the Add button and navigating to the PHP installation directory. Now select the PHP and click the Edit Button to configure the PHP. It shows the configuration wizard as shown in Fig 4. I have configured the PHP name, executable path, and the location of the php.ini file.

Fig 4

Now click the Debugger Tab and select the Xdebug as the debugger for the selected PHP version as shown in Fig 5. In case the Debugger Tab complains about the Xdebug installation by showing a warning, follow the above steps carefully and restart your Eclipse.

Fig 5

Press the OK Button to close the PHP Settings Dialog. It will show the configured debugger as shown in Fig 6.

Fig 6

Now press Apply and Close Button to close the Preferences Dialog. Configuring the debugger correctly is the most crucial step in order to debug PHP programs.

Basic Program to Debug

We will be updating the hello world program written in the previous section by adding a for loop to iterate and print the number spell on the console. The complete program is shown below.

<?php
$numbers = [ 'Zero', 'One', 'Two', 'Three', 'Four', 'Five', 'Six', 'Seven', 'Eight', 'Nine' ];

for( $i = 0; $i < 10; $i++ ) {    
    $number = $numbers[ $i ];
    echo $number . "\n";
}

Debug the Program

In this section, we will debug the program by adding a breakpoint at line number 6 as shown in Fig 7.

Fig 7

Double click the left bar against line number 6. It will add a breakpoint as shown in Fig 8.

Fig 8

The blue bubble on the left margin represents the breakpoint added by us. Now right click on the PHP program, hover on Debug As Option, and click on PHP CLI Application Option as shown in Fig 9.

Fig 9

In case you have not configured the xdebug.mode, it will simply execute the program and keep on waiting for the xdebug session as shown in Fig 10. It will show the message - Launching : Waiting for Xdebug session.

Fig 10

In case you have configured the xdebug.mode, it will show a dialog to switch to debug perspective as shown in Fig 11.

Fig 11

Click the OK Button to switch to debug perspective. The Debug Pointer will stop on line 1 as shown in Fig 12.

Fig 12 also shows the key buttons available for debugging.

Fig 12

Now, click the Step Over Button to execute the first statement. The pointer will move to line 4. We can also see that the variable $numbers is added on the Variables Stack as shown in Fig 13.

Fig 13

Again click the Step Over Button to execute the for statement. It will move the pointer to line 6 and also add the variable $i to the Variable Stack as shown in Fig 14. Similarly, if we again click the Step Over Button, it will add the variable $number to the variables stack showing its value set to Zero.

Fig 14

Now click the Resume Button and the normal execution starts until the code finds a breakpoint. The pointer will stop on line 6 since we have added a breakpoint on it. We can also see all the active breakpoints on the Breakpoints Panel as shown in Fig 15.

Fig 15

If we double click the breakpoint on line 6, it will be removed as shown in Fig 16.

Fig 16

Now again click the Resume Button and the program will be fully executed since the pointer won't find any other breakpoint. The complete output will be shown on the console as shown in Fig 17.

Fig 17

This is how we can debug a PHP program using Eclipse on Windows.

Summary

This tutorial provided the reference links to install PHP 7, PHP 8, WampServer, XAMPP, and Eclipse for PHP on Windows 10. It also provided all the steps required to debug the PHP program in CLI mode.