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
dumpj($variable);
ddj($variable);  // Dump and die

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: 3 Web: 5	Maximum depth for object expansion
`maxItems`	int	CLI: 100 Web: 2000	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	2	Indentation size

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'
    ]
]);

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

$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 beautified

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));

Output marks:

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

Context Snapshots

use Anhoder\PrettyDumper\Context\ContextSnapshot;
use Anhoder\PrettyDumper\Context\DefaultContextCollector;

$collector = new DefaultContextCollector();
$snapshot = $collector->collect();

pd($snapshot);  // Includes request info, environment variables, stack, etc.

Testing

# Run all tests
composer test

# Run specific test group
./vendor/bin/pest --group=performance

# Static code analysis
composer phpstan

# Code style check
composer mago

Project Structure

src/
├── helpers.php              # Global helper functions
└── PrettyDumper/
    ├── Context/             # Context management
    │   ├── ContextSnapshot.php
    │   └── DefaultContextCollector.php
    ├── Formatter/           # Formatting engine
    │   ├── PrettyFormatter.php
    │   ├── FormatterConfiguration.php
    │   └── Transformers/    # Data transformers
    │       ├── ExceptionTransformer.php
    │       ├── JsonTransformer.php
    │       ├── SqlTransformer.php
    │       └── DiffTransformer.php
    ├── Renderer/            # Rendering layer
    │   ├── CliRenderer.php
    │   ├── WebRenderer.php
    │   └── DiffRenderer.php
    ├── Storage/             # Storage engine
    │   ├── MemoryStorage.php
    │   ├── FileStorage.php
    │   └── DumpHistoryStorage.php
    └── Support/             # Support modules
        ├── Frameworks/      # Framework integration
        │   ├── LaravelServiceProvider.php
        │   └── SymfonyBundle.php
        └── Themes/          # Theme system
            ├── ThemeRegistry.php
            └── ThemeProfile.php

public/assets/
├── css/pretty-dump.css      # Web styles
└── js/pretty-dump.js        # Interactive scripts

examples/
└── run-examples.php         # Interactive examples

tests/
└── FeatureTest.php          # Feature tests

Performance

✅ Renders 1M elements in ≤ 3 seconds
✅ Automatic circular reference detection
✅ Depth and item count protection
✅ Large string truncation mechanism

Browser Compatibility

Web rendering supports all modern browsers:

Chrome/Edge 90+
Firefox 88+
Safari 14+
Opera 76+

No-JavaScript environments can use native <details>/<summary> expansion.

Contributing

Issues and Pull Requests are welcome!

License

MIT License

Made with ❤️ by anhoder

anhoder / pretty-dumper

Maintainers

Details