Skip to content
/ debug Public

Collection of useful debugging utilities

License

Notifications You must be signed in to change notification settings

kuria/debug

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

32 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Debug utilities

Collection of useful debugging utilities.

https://travis-ci.com/kuria/debug.svg?branch=master

PHP 7.1+

Utilities for inspecting arbitrary values.

Dumping arbitrary PHP values with nesting and string length limits.

<?php

use Kuria\Debug\Dumper;

$values = [
    'foo bar',
    123,
    -123,
    1.53,
    -1.53,
    true,
    false,
    fopen('php://stdin', 'r'),
    null,
    array(1, 2, 3),
    new \stdClass(),
];

echo Dumper::dump($values);

Output:

array[11] {
    [0] => "foo bar"
    [1] => 123
    [2] => -123
    [3] => 1.530000
    [4] => -1.530000
    [5] => true
    [6] => false
    [7] => resource(stream#10)
    [8] => NULL
    [9] => array[3]
    [10] => object(stdClass)
}
  • see other arguments of dump() for nesting and string limits
  • if an object implements the __debugInfo() method, its output will be used instead of the properties
  • if an object implements the __toString() method, its output will be used instead of its properties if:
    1. it has no properties
    2. the properties cannot be displayed due to the nesting limit
  • if an object implements the \DateTimeInterface, its value will be formatted as a string

Safely dumping arbitrary strings. All ASCII < 32 will be escaped in C style.

<?php

use Kuria\Debug\Dumper;

echo Dumper::dumpString("Foo\nBar");

Output:

Foo\nBar

Useful for dumping binary data or examining actual bytes of a text.

<?php

use Kuria\Debug\Dumper;

echo Dumper::dumpStringAsHex("Lorem\nIpsum\nDolor\nSit\nAmet\n");

Output:

 0 : 4c 6f 72 65 6d 0a 49 70 73 75 6d 0a 44 6f 6c 6f [Lorem.Ipsum.Dolo]
10 : 72 0a 53 69 74 0a 41 6d 65 74 0a                [r.Sit.Amet.]
<?php

use Kuria\Debug\Dumper;

class Foo
{
    public static $staticProperty = 'lorem';
    public $publicProperty = 'ipsum';
    private $privateProperty = 'dolor';
}

print_r(Dumper::getObjectProperties(new Foo()));

Output:

Array
(
    [staticProperty] => ReflectionProperty Object
        (
            [name] => staticProperty
            [class] => Foo\Foo
        )

    [publicProperty] => ReflectionProperty Object
        (
            [name] => publicProperty
            [class] => Foo\Foo
        )

    [privateProperty] => ReflectionProperty Object
        (
            [name] => privateProperty
            [class] => Foo\Foo
        )

)

Utilities related to PHP's output system.

<?php

use Kuria\Debug\Output;

// clean all buffers
Output::cleanBuffers();

// clean buffers up to a certain level
Output::cleanBuffers(2);

// clean all buffers and catch exceptions
$bufferedOutput = Output::cleanBuffers(null, true);
<?php

use Kuria\Debug\Output;

// capture all buffers
Output::captureBuffers();

// capture buffers up to a certain level
Output::captureBuffers(2);

// capture all buffers and catch exceptions
$bufferedOutput = Output::captureBuffers(null, true);

Replace all headers (unless they've been sent already):

<?php

use Kuria\Debug\Output;

Output::replaceHeaders(['Content-Type: text/plain; charset=UTF-8']);

PHP error utilities.

<?php

use Kuria\Debug\Error;

var_dump(Error::getName(E_USER_ERROR));

Output:

string(10) "E_USER_ERROR"

Exception utilities.

<?php

use Kuria\Debug\Exception;

$invalidArgumentException = new \InvalidArgumentException('Bad argument', 123);
$runtimeException = new \RuntimeException('Something went wrong', 0, $invalidArgumentException);

echo Exception::render($runtimeException);

Output:

RuntimeException: Something went wrong in example.php on line 6
#0 {main}

Including all previous exceptions and excluding the traces

<?php

echo Exception::render($runtimeException, false, true);

Output:

[1/2] RuntimeException: Something went wrong in example.php on line 6
[2/2] InvalidArgumentException (123): Bad argument in example.php on line 5
<?php

use Kuria\Debug\Exception;

try {
    try {
        throw new \InvalidArgumentException('Invalid parameter');
    } catch (\InvalidArgumentException $e) {
        throw new \RuntimeException('Something went wrong', 0, $e);
    }
} catch (\RuntimeException $e) {
    $exceptions = Exception::getChain($e);

    foreach ($exceptions as $exception) {
        echo $exception->getMessage(), "\n";
    }
}

Output:

Something went wrong
Invalid parameter

Joining exception chains has some uses in exception-handling code where additional exception may be thrown.

<?php

use Kuria\Debug\Exception;

$c = new \Exception('C');
$b = new \Exception('B', 0, $c);
$a = new \Exception('A', 0, $b);

$z = new \Exception('Z');
$y = new \Exception('Y', 0, $z);
$x = new \Exception('X', 0, $y);

// print current chains
echo "A's chain:\n", Exception::render($a, false, true), "\n\n";
echo "X's chain:\n", Exception::render($x, false, true), "\n\n";

// join chains (any number of exceptions can be passed)
// from right to left: the last previous exception is joined to the exception on the left
Exception::joinChains($a, $x);

// print the modified X chain
echo "X's modified chain:\n", Exception::render($x, false, true), "\n";

Output:

A's chain:
[1/3] Exception: A in example.com on line 7
[2/3] Exception: B in example.com on line 6
[3/3] Exception: C in example.com on line 5

X's chain:
[1/3] Exception: X in example.com on line 11
[2/3] Exception: Y in example.com on line 10
[3/3] Exception: Z in example.com on line 9

X's modified chain:
[1/6] Exception: X in example.com on line 11
[2/6] Exception: Y in example.com on line 10
[3/6] Exception: Z in example.com on line 9
[4/6] Exception: A in example.com on line 7
[5/6] Exception: B in example.com on line 6
[6/6] Exception: C in example.com on line 5

Simplified real-world example

Without joining exception chains
<?php

use Kuria\Debug\Exception;

// print uncaught exceptions
set_exception_handler(function ($uncaughtException) {
    echo Exception::render($uncaughtException, false, true);
});

try {
    // some code which may throw an exception
    throw new \Exception('Initial exception');
} catch (\Exception $exception) {
    // handle the exception
    try {
        // some elaborate exception-handling code which may also throw an exception
        throw new \Exception('Exception-handler exception');
    } catch (\Exception $additionalException) {
        // the exception-handling code has crashed
        throw new \Exception('Final exception', 0, $additionalException);
    }
}

Output:

[1/2] Exception: Final exception in example.php on line 20
[2/2] Exception: Exception-handler exception in example.php on line 17

Notice that the information about Initial exception is lost completely.

We could glue the Initial exception's info to the Final exception's message, but that would be rather ugly and hard to read.

With joining exception chains
<?php

try {
    // some code which may throw an exception
    throw new \Exception('Initial exception');
} catch (\Exception $exception) {
    // handle the exception
    try {
        // some elaborate exception-handling code which may also throw an exception
        throw new \Exception('Exception-handler exception');
    } catch (\Exception $additionalException) {
        // the exception-handling code has crashed

        // join exception chains
        Exception::joinChains($exception, $additionalException);

        throw new \Exception('Something went wrong while handling an exception', 0, $additionalException);
    }
}

Output:

[1/3] Exception: Something went wrong while handling an exception in example.php on line 24
[2/3] Exception: Exception-handler exception in /example.php on line 17
[3/3] Exception: Initial exception in example.php on line 12

Now the Initial exception is accessible as one of the previous exceptions.