README

Powerful PHP debugging output tool for CLI and Web environments

Introduction

Pretty Dumper is a modern PHP debugging library that provides highly readable output for variables, exceptions, and stack traces. It supports both CLI colored output and Web HTML rendering, making debugging more efficient and intuitive.

✨ Core Features

🎨 Dual-Mode Rendering - CLI colored output & Web HTML interface
🌓 Theme System - Built-in light/dark themes with auto-switching
🔍 Depth Control - Smart recursive rendering with circular reference detection
🛡️ Sensitive Data Protection - Auto-redaction of passwords, tokens, etc.
🚀 High Performance - Renders 1M elements in ≤ 3 seconds
♿ Accessibility - WCAG AA compliant
🔗 Framework Integration - Native Laravel and Symfony support
💎 Advanced Features:
- Complete exception chain display
- SQL auto-detection and beautification
- JSON auto-parsing and display
- Diff comparison functionality
- Context snapshot capture

Installation

composer require anhoder/pretty-dumper --dev

Requirements: PHP ^8.0

Quick Start

Global Functions

// Basic usage
pretty_dump($variable);

// Shorthand
pd($variable);

// Dump multiple variables
dump($var1, $var2, $var3);

// Dump and die
dd($variable);

// Dump with options
pretty_dump($variable, [
    'maxDepth' => 5,
    'maxItems' => 100,
    'theme' => 'dark'
]);

// JSON format output (auto-detects and formats JSON)
dumpj($variable);
pdj($variable);     // JSON format with more options
ddj($variable);     // Dump and die with JSON format

CLI Command Line

# Basic colored output
pretty-dump --depth=4 "config('app')"

# JSON format output
pretty-dump --format=json 'json_encode(["id" => 42])'

# Read from stdin
echo '{"ok":true}' | pretty-dump --stdin --from=json

# Execute PHP file
pretty-dump --file=bootstrap/cache/inspect.php --depth=6

# Custom theme and indentation
pretty-dump --theme=dark --indent-style=tabs --depth=5 "\$data"

API Usage

use Anhoder\PrettyDumper\Formatter\PrettyFormatter;
use Anhoder\PrettyDumper\Renderer\CliRenderer;
use Anhoder\PrettyDumper\Formatter\FormatterConfiguration;

// Create configuration
$config = new FormatterConfiguration([
    'maxDepth' => 5,
    'maxItems' => 200,
    'stringLengthLimit' => 1000,
    'theme' => 'auto'
]);

// Create formatter and renderer
$formatter = PrettyFormatter::forChannel('cli', $config);
$renderer = new CliRenderer($formatter);

// Render output
echo $renderer->render($value);

Configuration Options

FormatterConfiguration Parameters

Parameter	Type	Default	Description
`maxDepth`	int	CLI: 6 Web: 10	Maximum depth for object expansion
`maxItems`	int	CLI: 500 Web: 5000	Maximum items to display in arrays/objects
`stringLengthLimit`	int	500000	String length limit (bytes)
`theme`	string	'auto'	Theme: auto/light/dark
`redactionRules`	array	See below	Sensitive data redaction rules
`indentStyle`	string	'spaces'	Indentation style: spaces/tabs
`indentSize`	int	CLI: 0 Web: 2	Indentation size
`autoDetectJson`	bool	false	Auto-detect and format JSON strings
`showPerformanceMetrics`	bool	false	Show rendering time and statistics

CLI Command Options

--help                     Show help information
--depth=N                  Object expansion depth
--format=json|cli          Output format
--theme=light|dark|auto    Theme selection
--color / --no-color       Enable/disable colors
--stdin                    Read from stdin
--file=PATH                Read from file
--from=php|json|raw        Input format
--max-items=N              Maximum items limit
--string-limit=N           String length limit
--expand-exceptions        Expand exception details
--show-context             Show context information
--indent-style=spaces|tabs Indentation style
--indent-size=N            Indentation size

Sensitive Data Redaction

Default redaction rules (case-insensitive field name matching):

[
    'password',
    'passwd',
    'pwd',
    'secret',
    'token',
    'api_key',
    'apikey',
    'access_token',
    'refresh_token',
    'private_key',
    'auth'
]

Custom redaction rules:

$config = new FormatterConfiguration([
    'redactionRules' => [
        'creditCard',
        'ssn',
        'phoneNumber'
    ]
]);

Auto-Detection Features

Pretty Dumper automatically detects and formats special data types:

SQL Auto-Detection ✨

SQL queries are automatically detected and beautified:

// Automatic detection - just dump the SQL string
$sql = "SELECT u.id, u.name FROM users u WHERE u.status = 'active' ORDER BY u.created_at DESC";
pd($sql);  // Automatically detected as SQL, formatted and highlighted!

// Works with complex queries too
$complexSql = "SELECT u.id, o.id FROM users u JOIN orders o ON u.id = o.user_id";
pd($complexSql);

Supports:

SELECT, INSERT, UPDATE, DELETE queries
Complex JOIN statements
Aggregation with GROUP BY and HAVING
Common Table Expressions (CTE)
Syntax highlighting for keywords, strings, and numbers
Works in both CLI and Web environments

JSON Auto-Detection

JSON strings can be automatically detected and formatted:

// Using dumpj() - auto-detects JSON
$jsonString = '{"users":[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}],"count":2}';
dumpj($jsonString);

// Or with manual option
pd($jsonString, ['autoDetectJson' => true]);

// With shorthand functions
pdj($data);        // JSON format
ddj($data);        // JSON format and die

Features:

Automatic JSON validation
Syntax highlighting (keys, strings, numbers, booleans)
Unicode and emoji support
Nested structure handling
Graceful fallback for invalid JSON

Diff Comparison ✨ NEW

Compare two values and visualize differences:

// Basic diff
use Anhoder\PrettyDumper\Formatter\Transformers\DiffTransformer;

$oldData = ['name' => 'John', 'age' => 30];
$newData = ['name' => 'John', 'age' => 31, 'city' => 'NYC'];

pd_diff($oldData, $newData);

// Diff with auto-detected JSON
$oldJson = '{"name":"Bob","age":25,"skills":["PHP"]}';
$newJson = '{"name":"Bob","age":26,"skills":["PHP","JavaScript"]}';
pd_diff($oldJson, $newJson);

// Auto-diff with last value
$value1 = ['count' => 10];
pd_auto_diff($value1);    // Store first value

$value2 = ['count' => 15];
pd_auto_diff($value2);    // Compare with stored value

// Diff and die
pdd_diff($oldData, $newData);

Output marks:

🟢 Added keys/values
🔴 Removed keys/values
🟡 Modified values
⚪ Unchanged values

Conditional Dumping ✨ NEW

Dump only when conditions are met:

// pd_when - dump when condition is true
$data = ['user' => 'Alice', 'status' => 'active'];
pd_when($data, fn($d) => $d['status'] === 'active');

// pd_when with boolean condition
$error = ['code' => 500, 'message' => 'Server error'];
pd_when($error, false);  // Won't dump

// pd_assert - assertion-based dumping
$response = ['status' => 200, 'data' => ['id' => 1]];
pd_assert($response, fn($r) => $r['status'] === 200, 'HTTP status should be 200');

// pd_assert with message
$user = ['name' => 'Bob', 'age' => 25];
pd_assert($user, fn($u) => $u['age'] >= 18, 'User must be an adult');

// Die after assertion
pdd_assert($config, fn($c) => $c['debug'] === true, 'Debug mode must be enabled');

// Die when condition met
pdd_when($criticalError, true);

Dump History ✨ NEW

Track and compare values across code execution:

// Compare with last dumped value at this location
$value = ['count' => 10];
pd_auto_diff($value);  // First run - just dumps

$value = ['count' => 15];
pd_auto_diff($value);  // Shows diff from previous value

// Clear all history
pd_clear_history();

// Clear specific location
pd_clear_history(__DIR__ . '/script.php:42');

Framework Integration

Laravel

'providers' => [
    // ...
    Anhoder\PrettyDumper\Support\Frameworks\LaravelServiceProvider::class,
],

Usage:

// Via container
app('pretty-dump')($value, ['maxDepth' => 4]);

// Use global functions directly
pd($user);
dd($request->all());

Symfony

return [
    // ...
    Anhoder\PrettyDumper\Support\Frameworks\SymfonyBundle::class => ['all' => true],
];

Web Environment


Output debug information:

```php
// Auto-detect environment and output
pd($data);

// Or force Web rendering
$formatter = PrettyFormatter::forChannel('web');
$renderer = new WebRenderer($formatter);
echo $renderer->render($data);

Advanced Features

Exception Handling

try {
    throw new \RuntimeException('Database connection failed', 500);
} catch (\Exception $e) {
    pd($e);  // Complete exception chain and stack trace
}

Output includes:

Exception message and code
Complete exception chain
Stack trace (with file and line numbers)
Variable snapshots

SQL Detection ✨ Automatic

SQL queries are automatically detected and beautified:

// Just dump SQL - no special function needed!
$sql = "SELECT u.id, u.name FROM users u WHERE u.status = 'active' ORDER BY u.created_at DESC";
pd($sql);  // Auto-detected as SQL and formatted!

// Complex queries work too
$complexSql = "SELECT 
    u.id,
    u.name,
    o.id as order_id,
    o.total
FROM users u
INNER JOIN orders o ON u.id = o.user_id
WHERE u.status = 'active'
ORDER BY o.created_at DESC";
pd($complexSql);

// Inside arrays
$data = [
    'user_query' => "SELECT * FROM users WHERE id = ?",
    'order_query' => "SELECT * FROM orders WHERE user_id = ?",
];
pd($data);  // All SQL strings auto-detected

Features:

Automatic detection of SELECT, INSERT, UPDATE, DELETE queries
Syntax highlighting (keywords, strings, numbers)
Proper indentation and formatting
Works seamlessly in both CLI and Web environments
No configuration needed - works out of the box!

For specialized SQL operations (with bindings, EXPLAIN, etc.), use pd_sql():

$sql = "SELECT * FROM users WHERE id = ? AND status = ?";
$bindings = [123, 'active'];
pd_sql($sql, $bindings, $pdo);  // With PDO connection for EXPLAIN

JSON Auto-Detection ✨

JSON strings can be automatically detected and formatted using dumpj() or the autoDetectJson option:

$jsonString = '{"users":[{"id":1,"name":"Alice"}]}';
dumpj($jsonString);  // Auto-detected as JSON

// Or with manual option
pd($jsonString, ['autoDetectJson' => true]);

// Works in arrays too
$apiResponse = [
    'user_data' => '{"id":1,"name":"Bob"}',
    'config' => '{"theme":"dark","language":"zh"}',
];
pd($apiResponse, ['autoDetectJson' => true]);

Diff Comparison

use Anhoder\PrettyDumper\Formatter\Transformers\DiffTransformer;

$oldData = ['name' => 'John', 'age' => 30];
$newData = ['name' => 'John', 'age' => 31, 'city' => 'NYC'];

pd(DiffTransformer::diff($oldData, $newData));