En/php debug

Welcome to Simone Giustetti's wiki pages.

Languages: English - Italiano

Introduction

Every software developer spends a certain amount of her/his working time searching and correcting errors; an activity commonly referred to as debug. There is no denying it: as long as we will have programs errors will exist and we will need fixes and workarounds for them. Every modern programming language comes with tools, both embedded or external, some more powerful than others, meant to help in fixing bugs. In this specific aspect PHP, a language widely used in developing dynamic web sites, is somewhat lacking when compared to similar tools. A gap that should be filled with release 5.6 and the introduction of an internal debugger, a tool to allow developers to follow the source code flow while in execution. The following paper will instead describe some tools to debug PHP source code written with older releases of the language. Tools complementing the internal debugger that prove to be invaluable to developers when maintaining production code.

PHP Language

PHP is a general purpose programming language aimed for fast script development, well suited for producing dynamic web pages. In this specific configuration PHP is executed on a remote server where it generates HTML pages then sent to a web browser. Users requesting web pages will receive them without any sign of server executed PHP code.

While fast web site development is PHP main goal, the language can be used to write scripts that don't need any server and are able to run on a local host from the command line. Such scripts are ideal for repetitive tasks, even complex ones, and can be scheduled through the operating system provided scheduling services. Local scripts do not require any web server, browser, database or other service but only need the PHP language parser.

PHP Development

Whatever the reason to use PHP, writing code proves to be a fairly simple task and requires neither specific tools nor development environments, but only:

The language parser.
A text editor of choice.

Once the two listed prerequisites are installed you can start writing PHP code. To execute the completed script open a terminal emulator and run command:

  php -f <script>

where <script> is the text file containing the lines of code. Execute the command in the directory where your scripts are located. Feedback messages, warnings and error messages produced by the code will be output to video during execution.

PHP and Syntax Analysis

PHP bare installation provides some tools useful when searching trough the source code for errors. Executing a syntax analysis of PHP code is a fairly straightforward task provided local access to the scripts is granted. To check the syntax of script hello_world.php placed inside directory /home/sviluppo/php/ open a shell or a similar terminal emulator an move to the directory:

  cd /home/sviluppo/php/

then run the php parser using option -l that forces a syntax check of the file:

  php -l ./hello_world.php

The parser will return

  bash-4.2$ php -l hello_world.php
  No syntax errors detected in hello_world.php

when no syntax error is found. Otherwise an error message related to the first issue encountered while parsing the code will be output to screen:

  bash-4.2$ php -l hello_world.php
  PHP Parse error:  syntax error, unexpected 'echo' (T_ECHO), expecting ',' or ';' in hello_world.php on line 3 
  Errors parsing hello_world.php

All of the error messages will show:

An error description.
The parsed line of code.

When an issue is resolved, run the command again and parsing will stop when the next error is found:

  bash-4.2$ php -l hello_world.php
  PHP Parse error:  syntax error, unexpected        <title>PHP Test</title' (T_CONSTANT_ENCAPSED_STRING) in hello_world.php on line 4
  Errors parsing hello_world.php

The procedure can be recursively repeated for each error found by the parser at every consecutive run. Once all issues are resolved, message "No syntax errors detected" will be output giving proof of source code syntax correctness.

Below are three PHP listings referring to the parser runs executed in the above lines. Some syntax errors, even really dumb ones, were added to the first two. The main difference among the two being the resolution of the bug at line 2 where an ";" character was added to close the line of code. The third and last listing contains the correct code.

hello_world.php - Listing 1: Contains many syntax errors.

   <?php
      echo '<html>'
      echo '   <head>';
      iechio '       <title>PHP Test</title>';
      echo '   </head>";
      echo'   <body>';
      echo '     <p>Hello World</p>'; ?>
      echo '</body>";
      echo '</html>';
   ?>

hello_world.php - Listing 2: The first parser signaled bug was resolved.

   <?php
      echo '<html>';
      echo '   <head>';
      iechio '       <title>PHP Test</title>';
      echo '   </head>";
      echo'   <body>';
      echo '     <p>Hello World</p>'; ?>
      echo '</body>";
      echo '</html>';
   ?>

hello_world.php - Listing 3: Correct syntax.

   <?php
      echo "<html>\n";
      echo "   <head>\n";
      echo "       <title>PHP Test</title>\n";
      echo "   </head>\n";
      echo "   <body>\n";
      echo "      <p>Hello World</p>\n";
      echo "   </body>\n";
      echo "</html>\n";
   ?>

PHP and Variable Content

Syntax analysis proves to be an useful tool for error spotting, but it mainly highlights mistypings and missing characters while typing code. Syntax errors are fairly easy to spot and correct. Logic errors are usually more difficult to find and resolve. Logic errors only show up while the code is in execution. To understand such errors requires to follow the code flow through the parsed files, understand their order of execution and print out a list of variables and their respective content. PHP offers a relatively scarce number of tools to perform such task: backtrace and dump functions.

Backtrace functions return a list of source code files parsed during execution and the respective calling functions. Two backtrace functions exist:

debug_backtrace().
debug_print_backtrace().

The former returns an associative array whose each component consists of:

The file containing the call.
The line of code responsible for calling another file or function.
The called file / function.
An array containing the list of parameters passed to the function ant their respective values.

Calls are listed in decreasing order with the last one at the top of the list. Reading the list top down through each previous call you'll reach the main script.

debug_print_backtrace only returns a list of function calls or file inclusions in decreasing order. Each line shows the called function or included file name, the file containing the call and the corresponding line number. The first line returned by debug_print_backtrace corresponds to the last executed call; searching forwards through the list it is possible to rebuild the source code flow.

The PHP provided dump functions return the list of variables available when calling the function and their respective values. Some dump functions are available:

get_defined_vars().
print_r().
var_export().
var_dump().

Function get_defined_vars returns a list of all defined variables available when calling it. The list is exported in the form of a multi-dimensional array whose every component is a variable. The remaining functions take a parameter corresponding to the searched for variable and return its name and value in slightly different formats.

Conclusions

A drawback in using the previously listed functions consists of the need to modify the source code. A common function driven debug session usually resolves in:

Deciding which file to begin the analysis with.
Writing some backtrace or dump functions in it accordingly to ones need.
Executing code to obtain the desired information.
Updating more source code files.
Repeating the above tasks until a bug is found and resolved.
Removing all the added lines of code to restore the program flow.

The procedure can result difficult and requires a lot of effort and time. It surely would be better to follow parser executed code flow without the need to update it. This proves to be impossible without installing and configuring some additional tools. Many of such freely available tools are based on xdebug, a software that will be thee subject of a future article dealing with its many features, installation and configuration procedures and bindings with some external developers tools.

For any feedback, questions, errors and such, please e-mail me at studiosg [at] giustetti [dot] net

External links

Languages: English - Italiano