rspade_system/app/RSpade/man/console_debug.txt

# CONSOLE_DEBUG

A powerful debugging system for RSpade applications that provides channel-based debug output across PHP and JavaScript with flexible filtering and configuration.

## OVERVIEW

The console_debug() function provides a unified debugging interface that works identically in both PHP and JavaScript. It outputs categorized debug messages that can be filtered by channel, making it easy to focus on specific areas of your application during development.

## BASIC USAGE

### PHP
```php
console_debug("AUTH", "User login attempt", $username);
console_debug("DISPATCH", "Processing route:", $route, $params);
console_debug("DB", "Query executed:", $sql);
```

### JavaScript
```javascript
Debugger.console_debug("UI", "Button clicked", buttonId);
Debugger.console_debug("AJAX", "API call", endpoint, params);
Debugger.console_debug("DOM", "Element rendered", element);
```

## CHANNELS

Debug messages are organized into channels. Common channels include:

• AUTH - Authentication and authorization events
• DISPATCH - Route dispatching and controller execution
• DB - Database queries and operations
• CACHE - Cache operations (get, set, clear)
• BUNDLE - JavaScript/CSS bundle compilation
• UI - User interface events and interactions
• AJAX - AJAX calls and API requests
• DOM - DOM manipulation and rendering
• TEST - Test-specific debug output
• BENCHMARK - Performance timing information

You can create custom channels by simply using them in your console_debug() calls.

## CONFIGURATION

Configuration is managed in `config/rsx.php` under the `console_debug` section:

```php
'console_debug' => [
    'enabled' => env('CONSOLE_DEBUG_ENABLED', false),
    'outputs' => [
        'cli' => env('CONSOLE_DEBUG_CLI', false),
        'web' => env('CONSOLE_DEBUG_WEB', true),
        'ajax' => env('CONSOLE_DEBUG_AJAX', true),
        'laravel_log' => env('CONSOLE_DEBUG_LOG', true),
    ],
    'filter_mode' => env('CONSOLE_DEBUG_FILTER_MODE', 'whitelist'),
    'whitelist' => ['AUTH', 'DISPATCH', 'UI', 'AJAX'],
    'blacklist' => [],
    'include_benchmark' => env('CONSOLE_DEBUG_BENCHMARK', false),
],
```

## FILTER MODES

The system supports four filter modes:

### all
Shows all console_debug messages regardless of channel.

### whitelist (default)
Only shows messages from channels listed in the whitelist array.

### blacklist
Shows all messages except those from channels in the blacklist array.

### specific
Only shows messages from a single specific channel set via CONSOLE_DEBUG_SPECIFIC.

## ENVIRONMENT VARIABLES

You can override configuration using environment variables:

• CONSOLE_DEBUG_ENABLED - Master switch (true/false)
• CONSOLE_DEBUG_FILTER - Override filter with channel name or ALL
• CONSOLE_DEBUG_CLI - Enable CLI output (true/false)
• CONSOLE_DEBUG_WEB - Enable browser console output (true/false)
• CONSOLE_DEBUG_AJAX - Include in AJAX responses (true/false)
• CONSOLE_DEBUG_LOG - Write to Laravel log (true/false)
• CONSOLE_DEBUG_BENCHMARK - Include timing prefixes (true/false)
• CONSOLE_DEBUG_LOCATION - Include file location (true/false)
• CONSOLE_DEBUG_BACKTRACE - Include stack trace (true/false)

## QUICK DEBUGGING

For quick debugging sessions, use the CONSOLE_DEBUG_FILTER environment variable:

```bash
# Show only AUTH channel
CONSOLE_DEBUG_FILTER=AUTH php artisan serve

# Show all channels
CONSOLE_DEBUG_FILTER=ALL php artisan serve

# With benchmarking
CONSOLE_DEBUG_BENCHMARK=true php artisan serve
```

## OUTPUT DESTINATIONS

### CLI Output
When CONSOLE_DEBUG_CLI is enabled, messages appear in stderr with cyan coloring:
```
[DISPATCH] Processing route: /dashboard
```

### Browser Console
When CONSOLE_DEBUG_WEB is enabled, messages appear in the browser's developer console:
```javascript
DISPATCH Processing route: /dashboard
```

### Laravel Log
When CONSOLE_DEBUG_LOG is enabled, messages are written to storage/logs/laravel.log:
```
[2024-01-15 10:23:45] local.DEBUG: [DISPATCH] Processing route: /dashboard
```

### AJAX Responses
When CONSOLE_DEBUG_AJAX is enabled, debug messages are included in AJAX response headers and automatically displayed in the browser console.

## BENCHMARKING

Enable benchmark timing to see how long operations take:

```bash
CONSOLE_DEBUG_BENCHMARK=true php artisan serve
```

Output includes timing in seconds since request start:
```
[12.3456] [AUTH] User authenticated: user@example.com
[12.4567] [DB] Query executed in 0.111s
```

## PLAYWRIGHT TESTING

The console_debug system integrates with Playwright testing via special headers:

• X-Console-Debug-Enabled - Force enable/disable
• X-Console-Debug-Filter - Override filter for test
• X-Console-Debug-Benchmark - Enable timing for test
• X-Console-Debug-All - Show all channels for test

These headers only work from localhost in non-production environments.

## JAVASCRIPT INTEGRATION

### Auto-batching
JavaScript console_debug messages are automatically batched and sent to the server every 2 seconds if laravel_log output is enabled.

### Error Logging
JavaScript errors are automatically captured and logged to the Laravel log when LOG_BROWSER_ERRORS is enabled in the environment.

### Synchronous Display
Messages appear immediately in the browser console, while server logging happens asynchronously in batches.

## BEST PRACTICES

### 1. Use Descriptive Channels
Choose channel names that clearly indicate the area of code:
```php
console_debug("PAYMENT_GATEWAY", "Processing transaction", $txn_id);
console_debug("EMAIL_QUEUE", "Message queued", $recipient);
```

### 2. Include Context
Pass relevant variables as additional arguments:
```php
console_debug("AUTH", "Login failed", $username, $ip_address, $attempt_count);
```

### 3. Avoid Sensitive Data
Never log passwords, tokens, or other sensitive information:
```php
// BAD
console_debug("AUTH", "Login attempt", $username, $password);

// GOOD
console_debug("AUTH", "Login attempt", $username, "***");
```

### 4. Use for Development Only
Console_debug is automatically disabled in production. Don't rely on it for production logging.

### 5. Clean Up After Debugging
Remove or comment out console_debug calls once you've fixed the issue:
```php
// console_debug("DEBUG", "Temporary debug point", $data);
```

## TROUBLESHOOTING

### Messages Not Appearing

1. Check if console_debug is enabled:
   ```bash
   php artisan tinker
   >>> config('rsx.console_debug.enabled')
   ```

2. Check your filter mode and channel:
   ```bash
   >>> config('rsx.console_debug.filter_mode')
   >>> config('rsx.console_debug.whitelist')
   ```

3. Use CONSOLE_DEBUG_FILTER=ALL to bypass filtering:
   ```bash
   CONSOLE_DEBUG_FILTER=ALL php artisan rsx:debug /
   ```

### Too Many Messages

1. Use whitelist mode with specific channels:
   ```php
   'filter_mode' => 'whitelist',
   'whitelist' => ['AUTH', 'ERROR'],
   ```

2. Use environment variable for temporary filtering:
   ```bash
   CONSOLE_DEBUG_FILTER=AUTH php artisan serve
   ```

### JavaScript Messages Not Logged

1. Ensure laravel_log output is enabled:
   ```php
   'outputs' => [
       'laravel_log' => true,
   ],
   ```

2. Check browser console for errors in batch submission.

## EXAMPLES

### Debugging Authentication Flow
```php
public function login(Request $request)
{
    console_debug("AUTH", "Login attempt", $request->ip());

    $credentials = $request->only(['email', 'password']);
    console_debug("AUTH", "Validating credentials for", $credentials['email']);

    if (Auth::attempt($credentials)) {
        console_debug("AUTH", "Login successful", Auth::id());
        return redirect('/dashboard');
    }

    console_debug("AUTH", "Login failed", $credentials['email']);
    return back()->withErrors(['email' => 'Invalid credentials']);
}
```

### Debugging AJAX Calls
```javascript
class UserController {
    static async fetch_profile(userId) {
        Debugger.console_debug("AJAX", "Fetching user profile", userId);

        try {
            const user = await User_Model.fetch(userId);
            Debugger.console_debug("AJAX", "Profile fetched", user);
            return user;
        } catch (error) {
            Debugger.console_debug("AJAX", "Failed to fetch profile", error);
            throw error;
        }
    }
}
```

### Debugging Database Queries
```php
public static function get_active_users()
{
    console_debug("DB", "Fetching active users");

    $query = static::where('is_active', true)
                   ->where('last_login', '>', now()->subDays(30));

    console_debug("DB", "Query SQL:", $query->toSql());
    console_debug("DB", "Query bindings:", $query->getBindings());

    $users = $query->get();
    console_debug("DB", "Found users:", $users->count());

    return $users;
}
```

## SEE ALSO

• php artisan rsx:debug - Test routes with console_debug enabled
• system/config/rsx.php - Main configuration file
• system/app/RSpade/Core/Debug/Debugger.php - PHP implementation
• system/app/RSpade/Core/Js/Debugger.js - JavaScript implementation

---
For more information, visit the RSX documentation or run:
php artisan rsx:man console_debug