Requirements

• Please READ this document.
  It will take you only a few minutes and will avoid problems afterwards.
  
  
• You can run any internet or intranet server, (i.e. Apache, IIS, ... on any platform) and use PHPDebugger to verify your scripts.
  The debug output is sent to an independent window call the Listener.
  This Windows application (called the Listener) communicates (through TCP/IP) with the PHP application you want to debug.
  As this communication is through TCP/IP, it doesn't matter where you run your PHP script and where you start the Listener.
  Note that your Windows environment must be 'dotNet' ready to run the Listener.
  Either you have installed already any dotNet component, or you can download the framework (i.e.run-time environment) from Microsoft here.
  See also 'Installation instructions' for more details.
  
  
• You will need to know the IP address or the computer name of the machine where you intend to run the Listener. In case this is the same computer,
  the computer name to use is 'localhost'.
  You'll also need a dedicated IP port. Normally, you have all ports available on your system unless it has been disabled for security reasons.
  The default port used by PHPDebugger is '9105'.
  Don't use any port number like 80 (used by your browser), 110 (used by mail), ...
  
  
• You will still need your actual intranet or internet test environment.
  You will have to continue to use your current test environment to debug your PHP scripts.
  PHPDebugger only helps you to do it in an efficient way but does NOT replace that environment.
  Note that PHPParser, which is part of PHPDebugger (see further down) needs write access to the directory that contains your PHP scripts.
  This is because PHPParser analyses your source before starting the debugging.
  It creates a temporary equivalent PHP script containing the necessary statements to work more efficiently.
  
  

Introduction

PHPDebugger can be used to help you debug your newly written or maintained PHP web pages.
It enables you to trace EVERYTHING that happens in your PHP script at execution time.
This trace can be a running trace (i.e. the trace output is scrolling), or an interactive trace leaving you time to think and control.
You can set breakpoints at several places, scroll through the trace, ...
When in interactive trace mode, you can take some actions using commands as explained in the chapter Using PHPDebugger.
This way, you can see exactly what is going on and take the necessary actions.

Trace output is not 'echoed as part of your HTML page.
It is redirected to the Listener which is part of PHPDebugger.
Working this way, your output HTML page is correctly displayed and is not deformed by unwanted 'echo' statements.
You must start the Listener before testing your script. PHPDebugger doesn't start it for you.
The Listener sits and waits until it is woken up by somebody (i.e. your PHP script) to record the trace output.
Once started, the Listener can be active for as long as you continue debugging your scripts.

PHPDebugger's Listener also keeps a log of all trace info.
It logs everything that happens in the debugger itself as well as the sources of the PHP routines you debug.
All recorded info can optionally be written to a file or be printed
(see the Listener's Initial screen Sample trace Logbook Search window).
Saving all PHPDebugger info is a way to keep an audit trail of your changes proving the way your application works.
Future maintenance can be easier if you dispose of a trace.

PHPDebugger can be conducted using a set of PHPDebugger commands.
These commands can be entered on the Listener's command field when you are in interactive trace mode, or can be part of the PHP routines you want to test.
In other words, you can 'drive' the Listener from within your PHP script.

For example,

- You can clear the output window on demand,
- Enter a loop you want to trace
- At loop exit, save the logged data to disk.

Using this facility, you can set up a debug script and rerun it every time you want to test your application.

PHPDebugger is a system that logs what happens in your PHP script.
That's its primary goal.
Now lets see how PHPDebugger works.

PHPDebugger consist of 3 parts:

• Part 1 is PHPParser.
  It runs through your PHP source script and inserts the necessary PHP statements that will link to the Listener (Part 3).
  The purpose is to add these instructions at the correct places and with the correct
  parameters. Of course there is a program called PHPCleaner to do the cleanup once
  you decide your application is ready.  
  
  
• Part 2 is a PHP routine.
  
  
  • A PHP routine (called PHPDebugger.php) that is called at execution time
    to communicate with the Listener.
    It is a class definition and should reside in a directory where it can be reached at execution time (using require_once).
    PHPParser distributes the default PHPDebugger.php routine for you.
    You don't have to do anything during installation.
    
    
• Part 3 is called the Listener.
  It is a Windows application that records the debug output.
  Working with the Listener and using its commands is explained in Using PHPDebugger.
  The Listener window is shown here.

Installation

• Making your Windows environment 'dotNet' ready.
  If you installed already any dotNet component, you can skip this topic.
  If not, you can download the framework (i.e.run-time environment) from Microsoft here.
  You should download and install the version corresponding with the language of your system.
  This must be done only once of course, and it will install some
  Microsoft .dll files.
  The installation takes about 5 minutes.
  
  
• PHPParser and the Listener both go to the PHPDebugger subdirectory.
  A matter of keeping things together.
  You can however install them in a directory of your own choice.
  PHPParser needs read access to your working directory with PHP sources.
  This directory is NOT the directory used by your server. It is a directory
  only used for editing.
  So, if you start maintenance on your scripts, you should copy the existing
  sources to this editing directory.
  PHPParser needs write access to the directory used by your server.
  During the parsing process, PHPParser 'enriches' your source (as read
  from your editing directory) and writes its output in the server directory.
  Maybe you will have to adapt your access path as defined in Windows.
  This output is an equivalent of your sources, enriched with the required instructions needed for debugging.
  
  
• The file 'PHPDebugger.php' must be accessible at execution time (using a 'require_once').
  PHPParser makes sure the it is available at any time.
  if there is an existing PHPDebugger.php routine in its output directory,
  it will not be overwritten giving you the possibility to customize in case you want to.
  
  
• Now edit the php.ini file.
  Have a look at the timeout value specified.
  The value must be set to a rather large value.
  This is to give you think time during interactive debugging.
  
  max_execution_time = 3600 ; Maximum execution time of each script, in seconds
  
  
  
• You may need to increase the following Apache timeout values (in httpd.conf file) for the same reason.
  
  #
  # Timeout: The number of seconds before receives and sends time out.
  #
  Timeout 300
   
  #
  # KeepAliveTimeout: Number of seconds to wait for the next request from the
  # same client on the same connection.
  #
  KeepAliveTimeout 15
  
  
• When running PHPParser, you can specify the computer name an IP port
  for the computer running the Listener.
  By default, 'localhost' is used as computer name, as for port 9105.
  You can specify the name of the computer running the Listener and the port number
  as parameter to PHPParser. (see Using PHPDebugger for more details).
  
  To get to know the computer name of the Listener,
  you can open Command Prompt (on the Listener machine) and execute 'ipconfig /all'.
  This will tell you the computer's IP address.
  Alternatively, you click Start, Settings, Control Panel, then select Network.
  The Identification tab tells you the computer name.
  If you still didn't find the name, you can look for a file called 'hosts'.
  The sample hosts file from Microsoft contains the following text:
  
  # Additionally, comments (such as these) may be inserted on individual
  # lines or following the machine name denoted by a '#' symbol.
  #
  # For example:
  #
  # 102.54.94.97 rhino.acme.com # source server
  # 38.25.63.10 x.acme.com # x client host
  
  127.0.0.1 localhost
  
  You can Use either the IP address or the computer name.

Using PHPDebugger

This paragraph explains how to use PHPDebugger.
Let's draw the scenario how you develop an application today.

Having analyzed the problem, you start writing some PHP code.
In real life, it means you copy code left and right and make the necessary changes.
Now and then you give it a try to see what's coming out.

It is clear that you want to put things correct from the start.
So, it is ideal to start debugging early in your project.
At this point in time, PHPDebugger should come in to assist you.

So,

• As a first step, you start the Listener (referred to as Part3)
  
  
• Rather than editing directly in the server directory, you do the editing in a working directory.
  We call this your 'edit' directory. You should edit the scripts in this
  directory and not directly in your 'server' directory because PHPParser
  reads from the edit directory, handles your script and writes its output to your server
  directory ready to test.
  
  We recommend to use an editor where you can set up user tools.
  Editplus or Ultraedit (among many others) give you the required possibilities.
  
  As you set up a so called user tool specify your edit directory as
  first parameter (input) and the directory name of your server as the second (output)
  
  The parser nicely formats your script, correctly indented, and inserts the required debug statements.
  If the parser works ok, you can start your browser and try your newly written or maintained PHP script.
  
• Have a look now at the PHPDebugger Listener screen, it will contain all debug output.
  All '$trace->write(...);' statements inserted by the parser redirect their output to the Listener who formats it in a tab page.
  Please read carefully what is logged as to understand PHPDebugger as good as possible.
  

• The Logbook tab contains info about what happened in PHPDebugger.
  That means, it is a track of everything the cooperation between the Listener, your PHP script (enforced by the parser) and yourself worked out.
  You see messages about starting the Listener, starting your script, opening new tabs, printing, saving info changing font, etc..
  Note that when you do an interactive trace, trace is stopped and restarted every time you hit enter on the Listener screen.
  So, in this case, you will see many 'trace started' messages in the logbook.
  
  
• the Current source tab contains the source of the scripts used.
  It is the source from the script as specified in the url, but also all 'included' or 'required' sources as long as they have been parsed before by PHPParser.
  This tab is for documentary reasons only.
  In fact it is a first step towards an integrated development environment as it will be announced later.
  
  
• The Search results tabs contains a reference to all the lines
  corresponding to the search you initiated using 'Find'.
  Search searches as well in the source text as in the variable contents.
  Note that instructions are marked with '*-*' and parameters to the instructions with '>>>'.
  In assignment statements, the arrow points to the field name (<-) rather
  than pointing to the contents (->).
  
  If you double click a line, the Listener will show the line in the trace.
  This will bring you to the point of interest in a fast and easy way.
  
  
• The Run x tabs are used to receive the output from your script.
  'Run 1' is opened when the Listener is started.
  If you don't open any new tab, 'Run 1' will be the only one used.
  You can create new tabs and direct the output to it simply by activating it.
  To create a new tab, click 'File' and 'New' or execute the command 'newtab'.
  This enables you to do several tests and compare the results afterwards.
  Or you can send the debug output from several PHP scripts or even iterations in a for loop, each to their own output tab.
  This can be achieved using 'run x' command from within your script.
  Remember that by default, it is the hilighted tab that is receiving the trace output.
  
  
  

Frequently Asked Questions

• - Why is there only a Windows version for the Listener?
  
  This is version 1.0. We do intend to build an equivalent versions for other operating systems in the near future.
  The reason is that all companies developing web applications will also dispose of a Windows environment.
  We can hardly believe someone doing web development without testing with Internet Explorer, Netscape or other browsers in a Windows environment.
  So, anyway, these people dispose of Windows clients and it should not be a big deal to install it in Windows.
  > But YES, there will be other versions in the near future.
  
  
• - Why is there only a Windows version for the parser?
  
  This is mainly for historical reasons.
  Some parts of PHPParser are based on existing code developed initially for other reasons than PHPDebugger.
  (see "How it started" for more info.)
  As this is 'proven technology' we consider it being the right way to start with this version.
  Here again, YES, there will be other versions in the near future.
  
  
• - The Listener shows lines that are not at all part of my source or not relevant to the instructions used.
  This renders debug output unreadable.
  
  Note that debugging output depends on line numbers in the source.
  If you add lines, or delete lines AFTER you ran PHPParser, the trace output will not be correct.
  So, stick to editing the 'real' source, save and run PHPParser every time.
  See also next question.
  
  
• - How can I run the parser without to many screen and/or mouse manipulations?
  
  Many editors, (at least the better once) dispose of the possibility to run tools.
  They enable you to define some form of macro behind a key combination.
  In will be behind a combination such as ctrl-anykey.
  If you have a closer look, you will surely find a way to
  - save the script,
  - run PHPParser,
  simply by clicking only one tool key.
  Then you switch to your browser and hit the 'refresh' key to do a new test.
  Having done that, you can have a look at the Listener output to verify the execution.

Listener Commands

Listener commands are instructions sent to the Listener to ask for a specific function.
In fact, it is an alternative to clicking buttons.
But, as the Listener is also driven by your PHP script, (enriched by PHPParser), the Listener accepts commands coming that way too.

Let's look at an example.
Imagine you want to save the trace output for later review.
You can then, after testing, click the 'save as' button.
The standard 'Save as' dialog will come up and ask you for a filename.
This is an action you can add to your PHP script as not to forget.
You do this by adding the following line at the point you want to save the output:

$trace->talk('-->save c:\\myscript.trc');

This example saves the trace output to the indicated file.
The facility enables you to set up some sort of trace scenario clearing, saving, switching tabs, etc

Note that the commands can also be entered in the Listeners command line once you switched to interactive trace.

Following is a list of the commands and their parameters and meaning.

• clear
  
  This command will clear the current output tab.
  Listener shows the info it received in the highlighted tab.
  This tab is never cleared by the Listener.
  You can clear it on demand using the 'clear' command.
  Note that the 'Logging' tab and the 'current source' tab can NOT be cleared.
  
  Example:
  
  On the command line, you just type clear.
  Of course nobody will ever use it, as there is a 'clear' button.
  From within a script:
  
  

  	$trace->talk('-->clear');	
  	

  
  
• die some_text
  
  While in interactive trace, you can enter a 'die' command to kill
  the running script.
  This is most usefull when a script gets in a loop.
  Anyway, while debugging, whenever you feel the script shouldn't continue,
  you can kill it using 'die'.
  The Listener passes the 'die' command on to the script who executes it
  as a normal 'die'.
  
  
• run x
  
  This command enables you to switch between output tabs.
  Having opened more than one tab, you can change the trace destination using the 'run' command. On the Listener screen, click the appropriate tab instead. From a script, do something like:
  
  

  	for ($a=0; $a<$b; $a++) {
  		....
  		if ($a==5)
  			$trace->talk('-->run 2');
  		else
  			$trace->talk('-->run 1');
  		....
  	}
  	

  In the above example, trace output for case 5 is directed to a separate tab.
  This could be done to limit and isolate trace output to what you have to investigate.
  
  
• save filename
  
  This command enables you to save the current tab to the indicated file.
  If the command is entered on the Listener's command line and the filename is not specified, the Listener will prompt for a filename.
  Example:
  
  

  	for ($a=0; $a<$b; $a++) {
  		....
  		if ($a==5) {
  			$trace->talk('-->run 2');
  			$trace->talk('-->clear');
  		}
  		if ($a==6)
  			$trace->talk('-->save d:\\usr\\case5.trace');
  		....
  	}
  	

  
  
• trace x
  
  This command enables you to switch between interactive an running trace.
  By default, PHPDebugger uses a running trace.
  To switch to interactive trace use
  
  

  	$trace->talk('-->trace i');
  	

  To switch to running trace:
  
  

  	$trace->talk('-->trace r');
  	

  To stop tracing for the rest of the script:
  
  

  	$trace->talk('-->trace o');
  	

  Other values than 'i', 'r' and 'o' are ignored.
  This command can not be entered on the command line.
  This is because the command line is not available with 'running' trace.
  You should click the buttons to change the trace mode.

Future developments.

We intend to extent PHPDebugger with a lot of extra features.
Currently we work on

• Other platforms
  Other platforms (i.e. Linux, Unix versions) will be announced in the
  near future.
  
  
• Comments
  Based on your remarks and suggestions, I'll extend PHPDebugger to
  turn it into a great product.
  
  
• Identifying projects
  This will enable you to work on several projects without having to change
  parameters for the parser, cleaner and listener.
  
  
• Setup
  This will be changed so that all parameters are set as part of a project
  and they will all be specified in an easy and interactive way.
  
  
• Integration
  We plan to integrate editing, parser and server in one application
  to build a complete IDE.
  

These and other things will be announced in the (near) future.
People registrant for PHPDebugger will notified by e-mail
and will be authorized to download these versions.