Dahbug

This script grew from the frustration when trying to log debug data with var_dump() or print_r(). If you have a large multidimensional array, or an object with circular references, those functions will just output to much data. To solve this I wrote this little script that writes debug data to a log file.

1. Installation & Configuration

Include dahbug.php in your index.php or add it to the auto_prepend_file setting in your php.ini. The file declares one class, dahbug that works as wrapper for the dump methods.

There are a few configuration options for the script. You will find them in the config.json file. If you wish to modify these settings, create a file called local.json and override them there.

Configuration

    log_file:         This is the file where the output will be printed. 
                      Remember that it has to be writable by the web server.
    output:           file: Logs dumps to log_file.
                      print: Prints (echo) dumps to output.
    label_format:     The format of the labels printed by the dump() method.
    string_format:    String format for the dump() method.
    timestamp_format: Format for the header timestamp. Checkout the PHP manual page for the
                      `date()` function for format options.
    print_timestamp:  If set to true, the timestamp will be added to the output header according
                      to the format specified in the `timestamp_format` option.
    print_filename:   If set to true, the filename and line number from where dump()
                      is called will be printed before the output.
    string_cap:       When strings are printed by dump() they will be capped to this length.
                      If set to 0 or false, string cap will be disabled.
    ascii_notation    "caret" or "escape". How to output non printable ascii characters.
                      eg. new line will be printed as ^J (caret) or \n (escape).
    line_endings:     The line ending format your terminal is using.
                      Can be set to: "LF" (linux), "CR" (old Mac) or "CRLF" (Windows)
    output_encoding:  The character encoding of your terminal, eg. "UTF-8", "ISO-8859-1",
                      "ASCII" etc... Accepts all values that are listed by `mb_list_encodings()`
    indent:           When printing arrays, each level will be indented this number of spaces.
    max_depth:        The maximum number of recursions (levels) when printing arrays.
    use_colors:       Set to true if you want to colorize terminal output.
    theme:            Select color theme. Themes are saved in <theme name>.theme files.
    color:            Terminal color values. Don't touch...
    escape_chars      Escape character map. Don't touch...

Color themes

You can create your own color themes. Just copy default.theme and change the colors. Valid color values for standard 16 color terminal can be found in the config.json file. For 256 color mode values, run php palette.php and it will print a palette with color values. Use the three digit values from the palette to create your theme.

2. Usage

Just make a static call to the method you want to use:

    dahbug::dump($var);

When you use any of the dump methods the output will be printed to the log file. I would recommed you to open a terminal and run tail -f <logfile> to see the output as the application is running..

When you make a request to a script, eg. http://example.com/some/path the following will be printed to the log file:

192.168.1.87 example.com GET /some/path

Request processing time: 6.46 ms   Memory Usage: 1 Mb

The debug output will be printed between those lines.

3. Example

I will use this code for the examples in the function reference

class foo
{
    protected $data;

    public function setData($data)
    {
        $this->data = $data;
    }

    public function getData()
    {
        return $this->data;
    }
}

class bar extends foo
{
    public function printData()
    {
        if ($this->_canPrint()) {
            print_r($this->data);
        }
    }

    protected function _canPrint()
    {
        return !empty($this->data);
    }
}

$bar = new bar;
$bar->setData(array(
    'some_string' => 'Foo Bar Baz',
    'a_numer' => 123,
    'an_array' => array(
        'more' => 'String',
        'data' => 123
    ),
    'an_object' => new stdClass()
));

4. Function Reference

• dump() Dump variables and formated printing.
• methods() Dumps class methods or method code.
• backtrace() Prints a backtrace.
• write() Outputs text.
• hex() Prints a hex dump.
• nl() Prints a newline.

dump

Formats and prints debug information of data.

Arrays and objects will be printed recursively, but only as many levels as specified in the max_depth config option or by the third function parameter ($maxDepth).

Strings will be capped to the length specified in config.json.

    mixed dump(mixed $var, string $label = null, int $maxDepth = null)

• $var The variable to dump. This will also be the return value.
• $label [optional] You can pass a string here to be used as label in your log.
• $maxDepth [optional] The maximum recursion depth when printing arrays.

Example:

Adding dahbug::dump($bar); to the end of the example script will output:

192.168.1.87 test.dev GET /dahbug/example.php

 In file /var/www/dahbug/example.php:44
  [$bar] = (object:1) bar
    [*data] => (array:4) 
        [some_string] => (string:11:ASCII) 'Foo Bar Baz'
        [a_numer] => (int) 123
        [an_array] => (array:2) 
            [more] => (string:6:ASCII) 'String'
            [data] => (int) 123
        [an_object] => (object:0) stdClass

Request processing time: 13.81 ms   Memory Usage: 1 Mb

methods

This method prints the class methods of an object or a class and its parents. Also prints the source code of a method if specified.

    void methods(mixed $object, string $method = null)

• $object The object you want to print the methods from.
• $method [optional] If you pass a method name the source code and php doc of that method will be printed.

Example:

Adding dahbug::methods($bar); to the end of the example script will output:

192.168.1.87 test.dev GET /dahbug/example.php

 In file /var/www/dahbug/example.php:44
 class bar
    printData ()

 extends foo
    setData ($data)
    getData ()

Request processing time: 3.40 ms   Memory Usage: 1 Mb

As you can see, only the public methods are listed.

Adding dahbug::methods($bar, 'printData'); to the end of the example script will output:

192.168.1.87 test.dev GET /dahbug/example.php

defined in class bar
  file /var/www/dahbug/example.php:20

    public function printData()
    {
        if ($this->_canPrint()) {
            print_r($this->data);
        }
    }

Request processing time: 6.46 ms   Memory Usage: 1 Mb

backtrace

Prints a backtrace.

    void backtrace()

write

Prints a string to the log without formating the text.

    void write(mixed $var, string $encoding = null)

• $var The variable to print. If an object is passed, the __toString() method will be called to generate the output.
• $encoding Force encoding of output to this encoding.

hex

Prints a hex dump of a binary string.

    void hex(string $bin)

• $bin The binary string you want to dump.

nl

Prints a new line to the log file.

    void nl()