README

Built-in debugging system for PHP development with Phage. Simple and elegant debugging tool with zero configuration.

Features

📝 Logging - Log messages with context
🔍 Collapsible Variables - Inspect variables with expandable tree view
🎨 Syntax Coloring - Color-coded display by type
📦 Object Inspection - View properties (public/protected/private)
⏱️ Performance Measurement - Measure execution time and memory
🗄️ SQL Logging - Log database queries with bindings
❌ Exception Handling - Capture and analyze exceptions
📊 Table Display - Display data as formatted tables
📡 HTTP Requests - Log HTTP requests and responses
🔄 Stack Traces - Get detailed stack traces
✨ Zero Configuration - Works out of the box
📡 Real-time Updates - Live WebSocket connection to debug UI
💾 Persistent History - SQLite database backend

Installation

Install via Composer:

composer require happytodev/phage-debug

Requirements

PHP 7.4 or higher
Phage debug server running on http://localhost:23517 (default)

Quick Start

1. Make sure the Phage debug server is running:

./phage debug:start

2. Use in your PHP code:

<?php

use Phage\Debug\Debug;

// Simple logging
Debug::log('Application started');
Debug::log('User data', $user);

// Dump variables with interactive tree view
Debug::dump($_GET, $_POST, $complexArray);

// Log queries
Debug::sql('SELECT * FROM users', [], 0.045);

// Log exceptions
try {
    // ...
} catch (Exception $e) {
    Debug::exception($e);
}

// Measure performance
Debug::measure('Database Query', function() {
    return User::all();
});

// Display as table
Debug::table($users, 'Active Users');

// Pretty-print JSON
Debug::json(['status' => 'success', 'data' => $data]);

3. Open the debug UI:

./phage debug:open

Or manually open: http://localhost:23517

UI Features

The debug UI displays:

Collapsible Arrays:

▶ Array(5)
  [0]: "item1"
  [1]: "item2"
  [id]: 123

Collapsible Objects:

▶ User(4 properties)
  $id (private): 123
  $name (private): "John Doe"
  $email (private): "john@example.com"
  $roles (protected): Array(2)
    [0]: "admin"
    [1]: "user"

Primitive Types:

string: "Hello World"
integer: 42
float: 3.14
boolean: true
null: null

Configuration

Configure globally in your bootstrap code:

use Phage\Debug\Debug;

Debug::config([
    'enabled' => true,
    'endpoint' => 'http://localhost:23517/api/payloads',
    'async' => true,           // Non-blocking requests
    'timeout' => 0.5,          // 500ms timeout
]);

Or configure individually:

Debug::setEndpoint('http://192.168.1.100:23517/api/payloads');
Debug::setOrigin('my-project');

API Reference

Logging & Dumping

Debug::log(...$messages) - Log messages with optional context
Debug::dump(...$vars) - Dump variables with full tree view

Measurement

Debug::measure($label, $callback) - Measure execution time and memory
Debug::sql($sql, $bindings, $time) - Log SQL queries with bindings
Debug::exception($throwable) - Log exceptions with stack trace

Data Display

Debug::table($data, $label) - Display data as formatted table
Debug::json($data, $label) - Pretty-print JSON
Debug::http($method, $url, $headers, $body, $duration) - Log HTTP requests

Utilities

Debug::trace($label) - Get current stack trace
Debug::enable() - Enable debugging
Debug::disable() - Disable debugging
Debug::isEnabled() - Check if debugging is enabled

Advanced Usage

Disable for Production

if (env('APP_DEBUG')) {
    Debug::enable();
} else {
    Debug::disable();
}

Custom Origin

// Defaults to composer.json "name" field
Debug::setOrigin('my-custom-project-name');

Remote Debugging

Connect to a remote Phage debug server:

Debug::setEndpoint('http://192.168.1.100:23517/api/payloads');
Debug::log('Log from remote client');

Synchronous Mode

By default, debug requests are non-blocking (async). Force synchronous mode:

Debug::config([
    'async' => false,  // Wait for responses
    'timeout' => 2.0,  // 2 second timeout
]);

How It Works

Your PHP code calls Debug::log(), Debug::dump(), etc.
The package serializes the data (arrays, objects, primitives) into a detailed structure
A non-blocking HTTP POST request sends the data to the Phage debug server
The server broadcasts the payload to connected WebSocket clients (the UI)
The UI renders the data with interactive collapsible trees
Data is also persisted in SQLite for history

Supported Types

Primitives: null, bool, int, float, string
Collections: array (with unlimited nesting)
Objects: Any PHP object (with property inspection)
Special: DateTime objects with formatted display

Recursion Limit

To prevent infinite loops with circular references, the package limits recursive depth to 10 levels. Deeper nesting is truncated with a [Max depth reached] indicator.

License

MIT License - see LICENSE file for details

Support

For issues, questions, or contributions:

Repository: https://github.com/happytodev/phage-debug
Packagist: https://packagist.org/packages/happytodev/phage-debug
Issues: https://github.com/happytodev/phage-debug/issues

Author

HappyToDev

happytodev / phage-debug

Maintainers

Details