Gubed

10 min read

Setting up Quanta with Gubed to debug PHP scripts

Gubed is a Program designed to take control of PHP-scripts running on a webserver, thus enabeling the script author to debug these from within a so called ‘Debug-Client’. Although Gubed is still in an early project phase, it already provides the basic debugging-functions: it can start,stop,pause a script, set breakpoints, watch variables etc…
This Document describes from a user’s prespective, how to install,setup and run Gubed with the famous web-editor Quanta (now in kde-module ‘kdewebdev’), which recently got the long awaited capability to act as a debug-Client.
First, I will list the software/versions which I ended up to use for the given task, all the following descriptions are only tested with this environment, and may not work at all with other packages/versions.
Note: at creation time of this document, I had kde 3.2.1/Gubed 0.0.6/Quanta BE2 - most of the following was evaluated with that combination, changes that happened in the meantime are marked as ‘Update’.
Ok, I know that the following Descriptions may be a bit confusing, especially with respect to the different Versions of Quanta and Gubed and the way they interact, so anyone who is not interested in finding out how this all has evolved in the past, but rather wants to know how to quickly get started with current Versions of Quanta and Gubed, may directly jump to the Quickstart Guide for kdewebdev 3.3 (or later).

KDE 3.x
Gubed- currently at Version 0.2.2
kdewebdev SVN
Quanta+.

For Quanta issues, you may also check out the kdewebdev FAQ for instructions on how to install Quanta from SVN. In addition, a local or remote Webserver (Apache) running PHP 4.3 or later is required. As a preface, I will give a short explanation (as far as I understand it ![](/uploads/symbole/emoticons/zwinker.png)) of how Quanta, webserver, PHP and Gubed server interact to provide the desired functionality. Basically, the Webserver running the PHP-script to debug, communicates with the Gubed-Server through TCP-IP (this is the reason why the IP-Adress of the machine running the Gubed-Server must be known to the webserver, as well as the Port to which the GubedServer listens), which, on the other hand, communicates with a 'debug client' (Quanta, in this case), which acts as an Interface for the user - showing him the source code of the script to debug along with information, which part (line) of the script is actually executed, as well as control options like 'run','pause','step','add watch' and so on to control the debug-session. In addition, the debug Client tells the Gubed Server what to do next, which forwards this request to the webserver actually running the script. Thus, the Gubed Server can be viewed as a bidirectional link between the webserver and the debug-Client, which would otherwise not know anything about each other. In this situation, with Quanta not only beeing a debug-Client, but also superb source editor, the whole system turns out to be a complete IDE, incl. debugger ! Those who would like some more technical explanation on how all this works should take a look in the 'Theory of Operation' document in the Gubed/docs Directory. Update (22.06.04): As of Gubed 0.0.9, the gubed server has been split up into 2 parts: the debug server part itself has been moved into the debug client (Quanta), the standalone part is now a proxy-server to be used in a situation where a firewall/router is in between the webserver and the debug client (this functionality is new and enhances the application range significantly).

Installation:

For KDE, Apache+PHP, please refer to your distro’s documentation, Gubed and Quanta CVS will have to be built from source.
For Gubed, there are 2 tarballs on sourceforge, one (Gubed) contains the complete package incl. PHP-scripts and a standalone client (gbdwxGubed, which requires installation of wxWindows, a toolkit like qt, to build) - the other (GubedServer) contains the debugserver and the required PHP-scripts.. For now, we need the GubedServer package, as the wxgbdGubed Client is only needed in case one doesn’t plan to use Gubed with Quanta.
To build the server, unpack the tarball to a local directory, go to the ‘Server’ subdirectory, invoke the autogen.sh script to build configure, then ‘./configure;make;make install’ as usual (no special dependencies) - the debugserver should now be /usr/local/bin/gbdServer (provided, configure was invoked without other options - see ‘configure –help’).
Update (22.06.04): For Quanta from current CVS, GubedServer no longer needs to be built (as long as no router/firewall is in between, in which case the standalone gubed server acts as a proxy - enabled in quanta project settings by activation of the checkbox ‘proxy’), as this functionality is now built into Quanta ! (users of Quanta versions up to BE2 will still have to use the standalone Gubed Server 0.0.8 or earlier).
Then, move the ‘Gubed’ directory to a place under the DocumentRoot of the webserver, so that it can be accessed.
Building Quanta from source is not described here, but of course also required.
Update (25.08.04): As of kde 3.3, kdewebdev (includes quanta) is part of the official kde distribution, so there are now also binary packages available for various distributions - see the kde-download-link above.

Configuration:
Now, let’s look at the configuration of the 3 relevant parts, the webserver, the debug-server and the debug-client. As far as the webserver is concerned, configuration is done by including a special PHP-script into the target script to be debugged: Gubed.php - found in the above mentioned ‘Gubed’ directory in your DocumentRoot.
This script initializes variables etc. and also reads GubedGlobals.php, which is the very place to tell the webserver the IP address of the machine running the debugserver - note the debugserver does not necessarily have to run on the same machine as the webserver ! So, go ahead and adjust the settings in this file to the local requirements - here is mine:

   if(!isset($gbdDebugServer))
      #$gbdDebugServer = "localhost";
      $gbdDebugServer = "192.168.0.5";

   if(!isset($gbdDebugPort))
      $gbdDebugPort = 8016;

Note the commented ’localhost’ which is ok when all running on the same Computer… The debugport will mostly be left untouched, as long as port #8016 isn’t already in use for other services.
Update (22.06.04): from Gubed 0.0.9, the PHP-parts read the file ’localsettings.php’ from the gubed dir if it exists, this can hold all local settings and will not be overwritten by Gubed updates, so this is now the preferred place for customized settings like $gbdDebugServer above.
The debugserver needs no special configuration - nonstandard options can be passed to it via commandline - see the ‘Running’-section below.
Last, but not least, configure Quanta for work with the debugger:
In ‘project configuration’, select Gubed as the debugger - (If ‘Gubed’ does not show up in the drop down, make sure you do a ‘make install’ of Quanta or it won’t be able to find the plugin).
Complete the form under ‘Options’ with the required data.
Note that ‘Local Basedir’ means the directory where Quanta finds the project files, whereas ‘Server Basedir’ refers to the directory where the webserver can access them (should be the same as ‘Local Basedir’ in case the webserver runs on the same machine as Quanta, for me it is different as my apache runs on a remote machine, I can access that directory from Quanta via nfs). The ‘Server Host’ tab means the host where the debugserver and Quanta are running on - usually ’localhost’.
Update (25.08.04): There is no more ‘Server Host’ tab from Quanta/kdewebdev 3.3, as the debugserver is now built into Quanta.

Preparing PHP scripts to debug:

As noted, each script that should run under control of the debugger, needs to include Gubed.php mentioned above at the very start:

   // Include debugging backend
   require("../Gubed.php");

For a first test, I strongly recommend to use the test scripts that come with Gubed, located in the ‘Gubed/GubedTest’ directory.

Running:

Now we’re ready to start the whole thing:

fire up the debugserver from the commandline - 'gbdServer' (evtl. with options for nonstandard ports etc. - try 'gbdServer --help' for a list of possible options) - you should get an output like this:
```
Gubed Debug Server v0.0.8
Copyright (c) 2003 Linus McCabe
GPL Software, see License.txt
Type “quit” to shut down the server or “help” for help
Script connecting will be paused
Awaiting connection on port 8026
Awaiting connection on port 8016
Accepted client on port 8016
Accepted client on port 8026
```
Update(22.06.04): this step is no longer needed for Quanta from Version 3.3, as the GubedServer is now ‘built into’ Quanta. This is true, as long as there is no firewall/router in between the webserver and the debug client, if there is one, the standalone gubed server has to be used anyways, as it acts now as a proxy - be sure to have activated the ‘proxy’-checkbox in Quanta’s project settings.

point your webserver to the PHP script to be debugged.
start Quanta, open the debug-test project and open the file 'index.php' in the editor
in Quanta, go to the 'Debug' tab, select 'Run' ('Start Session' should not be needed with the debugserver already running).
(hopefully) see the script beeing executed in Quanta line by line, watch the output in your webserver, play with 'pause','step'... (hint: to add a variable to the watch window, right-click on it in the source code.. - You can also watch expressions).
have fun :-)

## Other hints:

If you encounter 'unintentional' stops of debug execution, this may be due to uninitialized variables or other errors in your script - you can disable this behaviour by starting gbdSever with '--errormask 1794' command line option (or just put this in your ~/.gubed file).
From GubedServer 0.0.7a, errormask 1794 is the default setting, so this shouldn't be an extra need anymore ...
Proxy introduced from Gubed 0.0.9 - works now even behind routers/firewalls which do NAT (Network Address Translation).
Standalone GubedServer no longer required for appropriate debug-clients (Quanta) from Gubed 0.0.9
From Version 0.0.10, a new method of invoking the debugger is introduced, eliminating the need to include Gubed.php in each File to be debugged.

## Appendix - Quickstart Guide for kdewebdev 3.3: Anyone who has managed to install kdewebdev 3.3 wether on kde 3.2 or 3.3 (note: impossible for kde 3.1 !) can find a short summary on how to get started with Gubed here:

get Gubed from Version 0.0.10
unpack the Gubed subdirectoy to your webroot (or some place below where your webserver can find it)
edit the file GubedGlobals.php (or localsettings.php) to suit your needs (see above)
create a Quanta-Project in the Gubed directory and put the necessary settings for Gubed in your Project Properties . The correct path's (including the StartSession.php script that comes with Gubed and it's Parameter indicating where the webserver will find the script(s) to debug) are critical for proper operation - mistakes/typos here will usually result in breakpoints not working or other weird things...
proceed with Running - note there is no more extra 'Debug' Tab as described, the Debug-related Buttons are now in the main Toolbar.

Note that all this applies if you can access your webserver directly - if the webserver has to be accessed through NAT (Network Address Translation - means there is a router/firewall in between), you have to build and use the proxy-server that comes with Gubed.

And - last but not least - a note for those who like to be ‘on the bleeding edge’ and build kdewebdev from CVS on a regular basis:
There are special Gubed-packages out at Sourceforge.
They are called ‘CVS YYYY-MM-DD’, intended to be used with kdewebdev from CVS. The date indicates what date the package was created and it’s suitable for Quanta from CVS from that date and later.
Generally, if you keep your Quanta CVS tree up to date, use the CVS-package with the latest date.

Update (Feb. 2009):

Currently, there is no more active development in the kdewebdev 3.5 branch - however, there are efforts to port the whole suite to kde4. Anyhow, these efforts (found in kde SVN trunk) are still in an early state, not suited for end-users.
Meanwhile, the stable kde 3.5 version (which includes all of Gubed, kommander, klinkstatus…) is quite feature-complete and runs smoothly also in kde 4.x.

This text is published under the GNU Free Documentation License (FDL).