Debugging Coppermine PHP code with Xdebug

[406man]

A debugging add-on for PHP is Xdebug. This article describes how to configure and use it within the WAMP environment described in a separate posting. I've tried to include all the configuration items here and hope I haven't missed out any steps.

Xdebug Introduction
Beginning with some basics:
Xdebug 2 is "legacy" and works with PHP 5 – therefore Coppermine 1.5.x.
Xdebug 3 is current and works with PHP 7 and 8 – therefore Coppermine 1.6.x.
All of these areas need configuring correctly:

• Web browser – to set xdebug's mode of operation and communicate with the web server
• Apache web server (in WAMP) – to actually run PHP with Xdebug enabled
• VS Code - to receive Xdebug information, display it, and allow the programmer to interact with it

Xdebug can work in different modes with the main ones being trace and step debugging. Although I used trace initially I found step debugging to be far more useful. The remainder of this article describes how to get step debugging working.

Xdebug – web browser.
In Firefox download and install the Xdebug Helper add-on. This puts an icon which looks like a small insect in the right side of the URL box. It changes colour depending on the Xdebug mode. Left click on the icon to change the mode. For interactive step-by-step debugging you want Debug mode – which displays the icon in green when enabled.

Xdebug – web server.
This is a tricky bit because there are several places to get things wrong. You have to manually edit the PHP.INI file but it has to be the right one which is the PHP Module in the web server for the version of PHP that you are running. Left click on the WAMP icon and hover the mouse over PHP. A sub-menu will display. Click on the option:   php.ini [apache module]
Do not choose any other php.ini file as editing it will be irrelevant for web apps. Also be aware that each version of PHP has its own php.ini file so if you want to debug in multiple PHP versions you have to edit all the relevant php.ini files one-by-one after choosing the PHP version.  Once you click on the menu option described above, php.ini will open, probably in Notepad depending on your PC's settings. At the bottom of the file is the [xdebug] section. Be sure that xdebug.mode =debug    is included and comment out with a ";" character any other xdebug.mode lines. After making the change and saving, the web server needs to be restarted if it's running. Use WAMP's "restart all services" option to do this.

Xdebug – VS Code
There are multiple areas to set up and it seems quite complex until you get used to it. I've included a screenshot with most of these items shown while debugging the key plugin file codebase.php.

• In Settings the path to the PHP executable must be set up. It will look something like this:    "php.debug.executablePath": "C:\\wamp64\\bin\\php\\php8.0.26\\php.exe"
  Note the double back-slashes. Each time you use a different version of PHP you should set this to match. It is used to check syntax.
• To start debugging you need to: click the triangle in the column on the left side of the screen. It will ask you to create a launch.json file – see below
• A launch.json file has to be created. Most of this is done automatically and you will be prompted if it doesn't exist. Once it exists, there's nothing to do as no changes are normally needed.
• Start listening for Xdebug. Below the menu items at the top of the screen is a bar containing a drop down box. You need this to be set to "Listen for Xdebug" if you are working with PHP 7 or 8. This is Xdebug 3 but it only says Xdebug. If working with PHP 5 you need "Listen for Xdebug 2 (Legacy)" which is found in the "Add Configuration..." section. Xdebug 2 and 3 use different listening ports so need different configurations and json files
• To the left of the drop down box is a triangle which is a "Play" button. Press this. The triangle in the left column should have a figure 1 appear with it, indicated one instance of Xdebug listening.
• Somewhere near the top of the screen will be a set of step controls in a horizontal bar – run, step over, step into, step up, restart and stop. These are used to step through the code during the debug process
• You have to set a breakpoint where you want the code to pause. Use the File > Open File menu option to open the relevant PHP file containing the line where you want to pause. You will see the PHP code along with line numbers.  On the line where you want to pause click the mouse to the left of the line number and a red dot will appear. This indicates a break point is set and it will be listed in the Breakpoint list towards the bottom of the screen.

Running
Run your web application. Provided you have done all of the above, when the application gets to the breakpoint it should be interrupted. Don't forget to tell Xdebug to go into Debug mode by clicking on the bug symbol in the URL bar. The Windows task bar will burst into life and VS Code will show the line where the PHP code has paused. If this doesn't happen you've forgotten one of the configuration items or made a mistake. There's no easy way to check what you've missed, other than step through my list above. If your web application crashes with a blank white screen you can sometimes find useful clues in wamp64/logs/xdebug.log

Xdebug has a performance impact so it's wise to switch it off when you don't need it using Xdebug Helper's Disable option (via clicking in Firefox's URL box).

Step Controls
A brief description of the step controls in VSCode. These are in a small block near the top of the screen and can be moved left or right.
Go/Continue   -  Use this when you've finished debugging and want to let the script run to completion
Step Over – Steps through the code line by line but will not go into any functions.
Step Into – When stepping through the code you can go down a level into a function. The PHP code for the function will display and you can step through it with the same amount of control
Step out – When you're in a function, step out will complete running through the function and stop at the next line of code in the script that called the function
Restart – I didn't find this useful
Stop – Stops execution. If you do this and want to debug again you will have to press the relevant button to get VSCode to listen for the debugger.

Finally
Good luck with getting Xdebug working. It's worth getting to grips with it as it's an excellent tool.

---------------------------------------------------------------------
Debugging Command Line PHP
Not relevant to most of Coppermine but worth saying that Xdebug can be made to work with command line PHP applications (i.e.PHP is run in a Windows Command Window or Powershell window and doesn't use a web server) and VS Code. This may be useful if you write some non-web-based utility scripts. Update the php.ini file in the PHP executable directory (not the Apache module) to include xdebug.mode =debug in the [xdebug] section. You can find it by left clicking on the WAMP icon and going through the menus to get to PHP > php.ini [FCGI – CLI]
Then set a couple of environment variables in Windows' CMD.EXE window.
> set XDEBUG_MODE=debug       
> set XDEBUG_SESSION=1           <<< The value 1 here is irrelevant. The variable just needs to be set   
Then open your PHP script in VSCode and set a breakpoint in the same way as for a web application. Prepare the rest of the VSCode settings and controls ready for debugging in the same way as for a web-based PHP script. Run the script in the command window using, for example:
> C:\wamp64\bin\php\php8.2.0\php.exe test_script_name.php

The following PHP script will output some xdebug  PHP settings and should prove useful for troubleshooting:
<?php
echo "Starting KF test program\n";
echo xdebug_info();
echo "Finished KF test program\n";
?>

[406man]

For a while I've kept running into the problem when debugging PHP using Xdebug that long strings get truncated. This is particularly awkward when developing Coppermine plugins as, for example, the HTML for a web page might be assigned to a variable and passed into the plugin. When it's truncated you can't see what's in the whole variable (and therefore the whole screen).

Today I decided I needed to sort this out and managed to get it working. As usual the instructions for Xdebug were only partially helpful  and I had to piece the solution together from various forum postings. Here's what to do.

There are two places that need to be updated. Both of them must be changed.

1. PHP needs the following configuration parameter added to the php.ini file. When working in the WAMP environment it's the Apache web server version of the php.ini file that has to be edited. In the WAMP control panel it's labelled [apache module].
Add this to the [xdebug] section at the end of the file:

xdebug.var_display_max_data = -1   

After editing it the WAMP environment should have all services restarted so the change can take effect

2. The VSCode environment needs the relevant settings added to the first part of the configurations section of the launch.json file. Here's an extract from my launch.json file. The new section is the whole of the xdebugSettings block.  Note that this is just a piece of the code and is not complete. If you use VSCode you should already have some of the "configurations" settings so it should be obvious where the change has to be made.

    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "xdebugSettings": {
                "max_children": 128,
                "max_depth": 5,
                "max_data": -1
            }
        },

Restart VSCode so the change can take effect.
To copy it somewhere else, find the variable name in the list of variables when the debugger is at a suitable break point. Hover the pointer over the variable and right click the mouse. Choose "Copy Value" to copy to the clipboard and then paste it into an editor.