Developer Blog

  • Blog
  • /
  • Simple application debugging with PHPixie Debug
By Dracony on 10 May 2015

Build Status Test Coverage Code Climate HHVM Status
Author Source Code Software License

PHPixie Debug was created to improve PHP development in any environment. Of course if you are already using a web framework debugging tools are already provided, but when developing a library, solving a programming puzzle or even using WordPress the lack of a debugging toolset is hindering. Even basic functionality like convertieng errors to exceptions requires registering a special handler. PHPixie Debug can bootstrap you with a convenient environment in just two lines of code.

Exceptions and tracing

The Debug library tries to achieve the same level of usage ina console environment as we already have in web applications. When writing libraries for PHPixie I often wanted to have exception traces that would include the part of code that the exception happened in. Another problem with traces in php is that calling print_r(debug_backtrace()) directly can quickly result in a wall of text if any argument in the backtrace was an object with some dependencies. Using debug_print_backtrace() gives a better result, but still prints all array members and requires output buffering to assign the result to a variable. Let’s take a look at the PHPixie trace:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
<?php
require_once('vendor/autoload.php');
$debug = new \PHPixie\Debug();

try{
    throw new \Exception("test");

}catch(\Exception $e) {
    //Pretty print an exception
    $debug->exceptionMessage($e);
}

echo "\n-------\n";

//Automatic exception printing
//Will also display any logged messages
//(more on that later)
$debug->registerHandlers();

class Test
{
    public function a($string)
    {
        $array = array(1, 2);
        $this->b($string, $array);
    }

    public function b($string, $array)
    {
        $object = (object) array('t' => 1);
        $this->c($string, $array, $object);
    }

    public function c()
    {
        substr();
    }
}

$test = new Test();
$test->a("pixie");

Results in:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
Exception: test                                                       

5                                  
6 try{                                                                 
> throw new \Exception("test");                                    
8                                                                      
9 }catch(\Exception $e) {                                              

#0 D:\debug\examples\exceptions.php:7                                

-------                                                               

ErrorException: substr() expects at least 2 parameters, 0 given       

36 public function c()                                             
37 {                                                               
>> substr();                                                   
39 }                                                               
40 }                                                                   

#0 D:\debug\examples\exceptions.php:38                               
#1 D:\debug\examples\exceptions.php:38                               
    substr()                                                          
#2 D:\debug\examples\exceptions.php:33                               
    Test->c('pixie', array[2], stdClass)                              
#3 D:\debug\examples\exceptions.php:27                               
    Test->b('pixie', array[2])                                        
#4 D:\debug\examples\exceptions.php:43                               
    Test->a('pixie')                                                  

Logged items:                                                         

Note that the trace doesn’t include the handler that converted a PHP error into an exception, a lot of similar libraries forget to hide that part thus littering your trace. PHPixie Debug hides any of its handles for the traces.

Dumping variables
Dumping data can be done via a static \PHPixie\Debug::dump(), this is by the way the first PHPixie static method ever. The reason for such approach is that usually you delete such calls after you fix the issue, so the Debug library itself is never really a dependency of your application, thus massing it via DI is needless. But the static call will only work if the Debug library has been prior initialized, and it acts as a proxy to that instance. PHPixie will never have any actual static logic.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<?php
require_once('vendor/autoload.php');

use PHPixie\Debug;
$debug = new Debug();

Debug::dump("Array dump:");
Debug::dump(array(1));

Debug::dump("Short array dump:");
//Короткий дамп выводит минимум информации. 
//Это удобно например для вывода количества
//элементов массива или имя класса объекта
Debug::dump(array(1), true);

$object = (object) array('t' => 1);
Debug::dump("Object dump:");
Debug::dump($object);

Debug::dump("Short object dump:");
Debug::dump($object, true);

Debug::dump("Dump trace with parameters");
class Test
{
    public function a($string)
    {
        $array = array(1, 2);
        $this->b($string, $array);
    }

    public function b($string, $array)
    {
        $object = (object) array('t' => 1);
        $this->c($string, $array, $object);
    }

    public function c()
    {
        Debug::trace();
    }
}

$t = new Test();
$t->a("test");

Result:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
'Array dump:'

Array
(
    [0] => 1
)


'Short array dump:'

array[1]

'Object dump:'

stdClass Object
(
    [t] => 1
)


'Short object dump:'

stdClass

'Dump trace with parameters'

#0 D:\debug\examples\dumping.php:37
    PHPixie\Debug::trace()
#1 D:\debug\examples\dumping.php:32
    Test->c('test', array[2], stdClass)
#2 D:\debug\examples\dumping.php:26
    Test->b('test', array[2])
#3 D:\debug\examples\dumping.php:42
    Test->a('test')

Logging
To separate actual program output from debugging output usually developers store messages in some sort of array that they print afterwards. The problem with that approach is that if an exception happens or exit() is called those messages will not be printed. PHPixie debug always prints the log on exception and can register a handler to also do that whenever the script ends execution. Here are two examples:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
use PHPixie\Debug;
$debug = new Debug();

Debug::log("test");
Debug::log(array(3));

class Test
{
    public function a($string, $num)
    {
        Debug::logTrace();
    }
}
$t = new Test();
$t->a("test", 5);

//Ручной вывод сообщений
$debug->dumpLog();
``````php?start_inline=1
Logged items:

[0] D:\debug\examples\logging.php:7
'test'

[1] D:\debug\examples\logging.php:8
Array
(
    [0] => 3
)


[2] D:\debug\examples\logging.php:16
#0 D:\debug\examples\logging.php:16
    PHPixie\Debug::logTrace()
#1 D:\debug\examples\logging.php:20
    Test->a('test', 5)

And with automatic logging:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<?php

use PHPixie\Debug;
$debug = new Debug();

//Передав 'true' при регистрации хендлеров
//мы также включаем вывод лога в конце
//исполнения
$debug->registerHandlers(true);

Debug::log("test");

echo("Logged messages will be printed below");
``````php?start_inline=1
Logged messages will be printed now

Logged items:

#0 D:\debug\examples\log_handler.php:13
'test'

In conclusion
The main purpose of PHPixie Debug is not actually exception handling and tracing, it was designed to provide an OOP interface to PHP traces and variable dumping. This will in near future allow for the creation of a web debugged for PHPixie 3, all that is lacking is a nice web template for it. Its primary use as a standalone tool is to bootstrap your development environment in two lines of code and no additional dependencies. I hope next time when you’ll be solving a test puzzle for an interview or you’ll find yourself in need of some tracing in WordPress you’ll remember this little library and save some time of reading through debug_backtrace() output.

Demo
To try out PHPixie debug all you need to do is this:

1
2
3
4
5
6
7
8
9
10
11
git clone https://github.com/phpixie/debug
cd debug/examples

#если у вас еще нет Композера
curl -sS https://getcomposer.org/installer | php

php composer.phar install
php exceptions.php
php logging.php
php log_handler.php
php dumping.php

As with all the other PHPixie libraries the code is 100% unit tested and works with all versions of PHP 5.3+ (including nightly PHP7 and HHVM).

comments powered by Disqus