Debugging Tools and Techniques in phpDTS: A Complete Guide to devtools.php and Error Handling

The phpDTS repository ships with a built-in web-based debugging console via devtools.php, complemented by global error handling through gexit(), a $log buffer system, and output buffering controls for long-running maintenance scripts.

The phpDTS game server framework includes lightweight internal utilities for administrators and developers to inspect system state and perform maintenance without external dependencies. These debugging tools and techniques are implemented directly in the PHP codebase, centered around the browser-accessible devtools.php interface and supported by global logging mechanisms in include/common.inc.php.

The devtools.php Web Console

The primary debugging interface is devtools.php, a mini-admin panel that executes maintenance functions through a simple action-based switch. This tool allows authorized users to regenerate configuration files and refresh player data in real-time.

Generating Item and Title Lists

Located in include/devtools/printitm.func.php and include/devtools/printtitles.func.php, these functions scan the game database to build master lists:

// devtools.php action handler excerpt
$action = !empty($_POST['action']) ? $_POST['action'] : $_GET['action'];
if (isset($action)) {
    ob_start();
    switch ($action) {
        case 'print_itm':
            include GAME_ROOT.'./include/devtools/printitm.func.php';
            print_itm_namelist(); // generates itmlist_<gamecfg>.php
            break;
        case 'print_titles':
            include GAME_ROOT.'./include/devtools/printtitles.func.php';
            print_titles_list(); // generates titles_<gamecfg>.php
            break;
    }
    ob_end_flush(); flush();
}

The print_itm_namelist() function scans every map, shop, mix, and NPC definition to compile a unique array of item identifiers, writing the output to include/itmlist_*.php via the writeover() helper. Similarly, print_titles_list() collates achievement titles into include/titles_*.php.

Bulk Achievement and Title Updates

For database maintenance, include/devtools/achrevupdate.func.php provides achrev_update() and nicksrev_update():

case 'achrev_update':
    include GAME_ROOT.'./include/devtools/achrevupdate.func.php';
    achrev_update();     // bulk-update achievement data
    break;
case 'nicksrev_update':
    nicksrev_update();   // bulk-update title data
    break;

These functions walk through every player record to rebuild achievement and title caches, streaming progress directly to the browser.

Real-Time Output Configuration

To prevent timeouts during these long-running operations, devtools.php initializes specific output controls at the top of the file:

@ob_end_clean();                 // discard any previous buffer
header('Content-Type: text/HTML; charset=utf-8');
header('Cache-Control: no-cache');
header('X-Accel-Buffering: no');
@ini_set('implicit_flush',1);
ob_implicit_flush(1);
set_time_limit(0);               // unlimited execution time
@ini_set('zlib.output_compression',0);

These settings ensure that echo statements and log messages appear immediately rather than being buffered until script completion.

Global Error Handling with gexit()

The framework implements centralized fatal error management through the gexit() function defined in include/common.inc.php. This mechanism provides graceful degradation while preserving diagnostic information.

Fatal Error Management

When a critical error occurs, gexit() terminates execution and displays a formatted error page:

if (!$udata) {
    gexit($_ERROR['no_login'], __FILE__, __LINE__);
}

// Inside game logic
if ($someCriticalCheckFails) {
    gexit('Unexpected state – aborting.', __FILE__, __LINE__);
}

The function accepts a message string, file path, and line number, logging the incident before rendering the error template.

Error Page Templates

The error presentation layer uses two files:

• errorpage.php: Primary template for gexit() invocations
• error.php: Fallback handler for uncaught PHP errors

Both templates display user-friendly messages while revealing file and line details to administrators, bridging the gap between user experience and debugging requirements.

The $log Buffer System

Throughout the admin interface and debugging tools, phpDTS utilizes a global $log variable to accumulate HTML-formatted messages. This buffer allows incremental tracing without disrupting page layout.

global $log;
$log .= 'Current player count: ' . $db->result_one("SELECT COUNT(*) FROM {$tablepre}players") . '<br>';

When the page renders, accumulated log entries appear at the bottom of the output, providing a trace of database queries and state changes executed during the request.

Output Buffering for Long-Running Scripts

Beyond devtools.php, the repository employs output buffer control patterns for any script that might exceed PHP's default execution limits. The combination of ob_end_clean(), ob_implicit_flush(1), and set_time_limit(0) allows maintenance scripts to process thousands of records while streaming status updates to the browser or CLI.

Helper Functions for Debug Operations

The debugging tools rely on utilities defined in include/common.inc.php:

• writeover($filename, $content): Safely writes debug output to the filesystem, creating the file if necessary.
• chmod($filename, 0777): Sets permissions on generated config files to allow later editing.
• config($type, $gamecfg): Resolves logical config names (e.g., 'itmlist') to absolute paths like gamedata/itmlist_1.php.

These helpers abstract file operations, allowing debug scripts to focus on data collection rather than I/O handling.

Summary

• devtools.php provides a web-based console for generating item lists, title lists, and refreshing achievement data via actions like print_itm and achrev_update.
• gexit() in include/common.inc.php offers centralized fatal error handling with file and line reporting, rendered through errorpage.php.
• The $log buffer accumulates HTML-formatted debug messages throughout execution for retrospective analysis.
• Output buffering controls (ob_implicit_flush, set_time_limit(0)) prevent timeouts during bulk operations by streaming results in real-time.
• Helper functions like writeover() and config() standardize file operations across debugging utilities.

Frequently Asked Questions

How do I access the devtools.php debugging console?

Navigate to /devtools.php on your server while logged in as an administrator. The interface accepts action parameters via GET or POST to trigger specific maintenance functions like print_itm or achrev_update.

What is the difference between gexit() and standard PHP error handling?

gexit() provides controlled termination with a user-friendly error page template (errorpage.php), whereas standard PHP errors may expose sensitive paths or fail to render properly within the game framework's layout. It also accepts explicit file and line parameters for precise debugging.

How can I run debugging scripts from the command line instead of the browser?

Create a CLI wrapper that defines IN_GAME and includes the necessary files:

<?php
define('IN_GAME', true);
require __DIR__ . '/include/common.inc.php';
require __DIR__ . '/include/devtools/achrevupdate.func.php';
ob_start();
achrev_update();
ob_end_flush();

This approach allows cron jobs or manual terminal execution of the same functions available in devtools.php.

Why does devtools.php disable output buffering?

Long-running operations like bulk achievement updates may process thousands of player records. Disabling buffering via ob_end_clean() and ob_implicit_flush(1) ensures status messages appear immediately in the browser, preventing the appearance of a hung process and avoiding PHP's default timeout limitations through set_time_limit(0).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}