# 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`](https://github.com/amarillonmc/phpdts/blob/main/devtools.php), complemented by global error handling through `gexit()`, a `$log` buf...

- Repository: [Nemo Ma/phpdts](https://github.com/amarillonmc/phpdts)
- Tags: how-to-guide
- Published: 2026-02-24

---

**The phpDTS repository ships with a built-in web-based debugging console via [`devtools.php`](https://github.com/amarillonmc/phpdts/blob/main/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`](https://github.com/amarillonmc/phpdts/blob/main/devtools.php) interface and supported by global logging mechanisms in [`include/common.inc.php`](https://github.com/amarillonmc/phpdts/blob/main/include/common.inc.php).

## The devtools.php Web Console

The primary debugging interface is [`devtools.php`](https://github.com/amarillonmc/phpdts/blob/main/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`](https://github.com/amarillonmc/phpdts/blob/main/include/devtools/printitm.func.php) and [`include/devtools/printtitles.func.php`](https://github.com/amarillonmc/phpdts/blob/main/include/devtools/printtitles.func.php), these functions scan the game database to build master lists:

```php
// 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`](https://github.com/amarillonmc/phpdts/blob/main/include/devtools/achrevupdate.func.php) provides `achrev_update()` and `nicksrev_update()`:

```php
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`](https://github.com/amarillonmc/phpdts/blob/main/devtools.php) initializes specific output controls at the top of the file:

```php
@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`](https://github.com/amarillonmc/phpdts/blob/main/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:

```php
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`](https://github.com/amarillonmc/phpdts/blob/main/errorpage.php): Primary template for `gexit()` invocations
- [`error.php`](https://github.com/amarillonmc/phpdts/blob/main/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.

```php
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`](https://github.com/amarillonmc/phpdts/blob/main/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`](https://github.com/amarillonmc/phpdts/blob/main/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`](https://github.com/amarillonmc/phpdts/blob/main/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`](https://github.com/amarillonmc/phpdts/blob/main/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`](https://github.com/amarillonmc/phpdts/blob/main/include/common.inc.php) offers centralized fatal error handling with file and line reporting, rendered through [`errorpage.php`](https://github.com/amarillonmc/phpdts/blob/main/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`](https://github.com/amarillonmc/phpdts/blob/main//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`](https://github.com/amarillonmc/phpdts/blob/main/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
<?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`](https://github.com/amarillonmc/phpdts/blob/main/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)`.