inanepain/dumper

A little tool to help with debugging by writing a `var_dump` like message unobtrusively into a collapsible panel at the bottom of a page.

1.14.1 2023-06-27 09:04 UTC

Requires

• php: >=8.1
• inanepain/stdlib: >=0.3.1 || dev-master || dev-develop

Suggests

• ext-runkit7: Allows creating custom aliases for dump method
• inanepain/cli: Using the Pencil class makes setting console colours easy

UNLICENSE

• Philip Michael Raab

• debug
• assert
• dumper
• inane
• silence counter

README

Table of Contents

• 1. Overview
• 2. Install
• 3. Basic Usage
  • 3.1. Ease of use
• 4. Getting more out of Dumper
  • 4.1. Dumper: Aliases
  • 4.2. Dumper: Configuration
  • 4.3. Dumper: UI
  • 4.4. Dumper: Silence

1. Overview

A little tool to help with debugging by writing a var_dump like message unobtrusively to a collapsible panel at the bottom of a page.

2. Install

$ composer require inanepain/dumper

3. Basic Usage

Dumper works right out the box. Once installed via composer you can use it straight away to dump your objects using either method; dump or assert on the \Inane\Dumper\Dumper object.

The dump method is the default method and logs what it is given. Where as the assert has a test for its first parameter and only logs if the test fails (falsy).

basic usage

\Inane\Dumper\Dumper::dump($data, 'After marge process');
\Inane\Dumper\Dumper::assert(!$data->error, $data, 'After marge process'); // (1)

1. Logs if error is true

3.1. Ease of use

Dumper registers the shortcut functions dd and da that work just like calling \Inane\Dumper\Dumper::dump() or \Inane\Dumper\Dumper::assert().

basic shortcut usage

dd($data, 'After marge process');
da(!$data->error, $data, 'After marge process'); // (1)

1. Logs if error is true

4. Getting more out of Dumper

Some more or less helpful hints and tips regarding to usage of Dumper.

• custom aliases

• configuration

• ui

• silence

4.1. Dumper: Aliases

Creating a custom global function as an alias to \Inane\Dumper\Dumper::dump method.

Creating a custom alias for Dumper

\Inane\Dumper\Dumper::dumper('kickIt', 'shErr');

// you can now use your `kickIt` function the same as the `dump` method.
kickIt($data, 'Data after...'); // (1)
// what about `shErr`?
shErr(!$data->error, $data, 'Data after...'); // (2)

// without *ext-runkit7*. Note the $kickIt is a variable.
$kickIt($data, 'Data after...');
$shErr(!$data->error, $data, 'Data after...'); // (2)

1. The first parameter of the dumper method creates dump aliases akin to the dd function.

2. The second parameter sets the alias for assert akin to da.

That’s how easy it is to create a custom global shortcut function for Dumper.

4.2. Dumper: Configuration

Dumper has a few static public properties you can use to change some of the default behaviours.

4.2.1. enabled

Dumper starts enabled but should you wish all Dumpers related content gone. Disable it here.

default: true

config: turn off Dumper’s output

\Inane\Dumper\Dumper::$enabled = false;

4.2.2. bufferOutput

Write dumps last. Just before php terminates. Set to false to have dumps inserted as the occur at runtime.

default: true

config: turn off buffered output to print dumps inline

// Somewhere before using Dumper, or even after for a section of code and then turn buffer on again.
\Inane\Dumper\Dumper::$bufferOutput = false;
// some code loop probably
\Inane\Dumper\Dumper::$bufferOutput = true;

4.2.3. useVarExport

By default Dumper uses its own variable parser to generate the output. Here you can tell Dumper to use var_export instead.

default: false

config: set dumper to use var_export

// set value to true
\Inane\Dumper\Dumper::$useVarExport = true;

4.2.4. highlight

Set the colour theme dumper uses. The default is to use the colours already set in your php.ini file.

default: \Inane\Stdlib\Highlight::CURRENT

1. Available colours in \Inane\Stdlib\Highlight

   • CURRENT

   • DEFAULT

   • PHP2

   • HTML

config: set dumper colours

// set colour theme
\Inane\Dumper\Dumper::$highlight = \Inane\Stdlib\Highlight::PHP2;

4.2.5. expanded

Controls the initial expanded state of the Dumper panel.

default: false

config: dumper log panel initial state

// Create the Dumper panel expanded
\Inane\Dumper\Dumper::$expanded = true;

4.2.6. setColours

Allows setting custom cli colours or disabling cli colours completely.

default:

[
	'reset' => "\033[0m",		# console default
	'dumper' => "\033[35m",		# magenta
	'label' => "\033[34m",		# blue
	'file' => "\033[97m",		# while
	'line' => "\033[31m",		# red
	'divider' => "\033[33m",	# yellow
];

config: setting cli colours

// Remove cli colouring
\Inane\Dumper\Dumper::setConsoleColours(false);

// Setting default colours
\Inane\Dumper\Dumper::setConsoleColours([]);

// Remove cli colouring
\Inane\Dumper\Dumper::setConsoleColours(false);
// creating a colour using Pencil from `inanepain/cli`
$label = new \Inane\Cli\Pencil(colour: \Inane\Cli\Pencil\Colour::Green, background: \Inane\Cli\Pencil\Colour::Red, style: \Inane\Cli\Pencil\Style::SlowBlink);
// Then set colours for **file**, **label** and **reset**
\Inane\Dumper\Dumper::setConsoleColours([
	'file' => "\033[36m",
	'label' => "$label",
	'reset' => "\033[0m",
]);

4.3. Dumper: UI

Customising Dumpers look and feel.

4.3.1. Panel

This is done by setting the values of the following css variables and a few php class properties.

font size

Adjust the font size used by the Dumper panel.

• variable: --dumper-font-size

• default: smaller

max height

Adjust the maximum height allowed of the Dumper panel when opened.

• variable: --dumper-max-height

• default: 80vh

expanded

Controls the initial expanded state of the Dumper panel.

default: false

config: dumper log panel initial state

// Create the Dumper panel expanded
\Inane\Dumper\Dumper::$expanded = true;

4.3.2. Theme

Switching Dumpers theme is done in the php by changing a static property on the Dumper object.

highlight

Set the colour theme dumper uses. The default is to use the colours already set in your php.ini file.

default: \Inane\Stdlib\Highlight::CURRENT

1. Available colours in \Inane\Stdlib\Highlight

   • CURRENT

   • DEFAULT

   • PHP2

   • HTML

config: set dumper colours

// set colour theme
\Inane\Dumper\Dumper::$highlight = \Inane\Stdlib\Highlight::PHP2;

4.4. Dumper: Silence

You can use the \Inane\Dumper\Silence attribute to silence dumps, silence a specified number of dumps, only show a specified number of dumps then go silent, per class, method or function. The Silence attribute also allows you to set Silence’s initial state and then set a counter after which the state will toggle.

Basic Silence Usage

use Inane\Dumper\Silence as DumperSilence;

#[DumperSilence()]
function doFirst(): void {
	echo 'hello', PHP_EOL;

	dd(__FUNCTION__, 'one');
	dd(__FUNCTION__, 'two');
}


#[DumperSilence(false)]
function doSecond(): void {
	echo 'hello', PHP_EOL;

	dd(__FUNCTION__, 'one');
	dd(__FUNCTION__, 'two');
}

doFirst(); // (1)
// hello

doSecond(); // (2)
// hello
// doSecond, one
// doSecond, two

1. This only outputs the echo. The `dd’s are ignored.

2. Here the echo and dd output is displayed.

4.4.1. Toggling State

This feature of Silence lets you either enable or disable dumping after a specified number of dump requests have been made. This lets you log only a few items when iterating over a large collection.

If you specify a limit, Silence’s second parameter, the Silence instance will toggle its value after it has received that many check requests. i.e. Silent becomes verbose and vice versa.

Toggle Silence Usage

use Inane\Dumper\Silence as DumperSilence;

#[DumperSilence(false, 1)]
function doFirst(): void {
	echo 'hello', PHP_EOL;

	dd(__FUNCTION__, 'one');
	dd(__FUNCTION__, 'two');
}


#[DumperSilence(true, 1)]
function doSecond(): void {
	echo 'hello', PHP_EOL;

	dd(__FUNCTION__, 'one');
	dd(__FUNCTION__, 'two');
}

doFirst(); // (1)
// hello
// doFirst, two

doSecond(); // (2)
// hello
// doSecond, one

1. Now we have the echo and the value from the first dd request. Silence toggled false to true after 1 request so the second dd request was ignored.

2. This is the reverse of the first. Here only the first dd request is shown.

4.4.2. Advanced: Logging Silence checks

Actually geeky stuff would be a better way to describe this section. By default Silence checks are not shown in the Dumper panel but this can be enabled if you want to figure out why your toggles are not doing what you expect them to do.

To enable this this is one simple step, add Type::Silence to the Dumper::$additionalTypes array.

Logging Silence Requests

Dumper::$additionalTypes[] = Type::Silence; // (1)
// code
Dumper::$additionalTypes = []; // (2)

1. future Silence checks will be shown in the Dumper panel.

2. and Silence checks after this will no longer show in the Dumper panel.

Customising Silence checks

You can customise the Silence check logs per Silence instance to make them stand out from the rest by giving it a custom label and colour.

Customising Silence Logs

#[Silence(on: true, config: [
	'label' => 'Do Test This', // (1)
	'colour' => 'purple', // (2)
])]
function doThis(): void {
	dd(null, 'Dump nothing important'); // (3)
}

doThis(); // (4)
doThis(); // (4)
doThis(); // (4)

1. set custom label to appear in Dumper panel.

2. set custom colour for log entry in Dumper panel.

3. this will not be show due to Silence

4. a purple entry labelled Do Test This will be added every time this function is called