0 Day Analytics – PHP Error Module Developer Documentation

The PHP Error Tracker Module captures and persists PHP fatal errors, uncaught exceptions, warnings, deprecation notices, and other PHP error types into a dedicated database table. Unlike traditional error logging to debug.log, errors are stored in the database and survive log file rotations, WP_DEBUG toggles, and server restarts.

Key Capabilities

• Automatic capture of PHP fatal errors via shutdown handler
• Uncaught exception/error capture via custom exception handler
• SHA-256 deduplication — repeated errors increment a counter instead of creating new rows
• Automatic source identification (plugin, theme, WordPress core, or PHP)
• PII and secret redaction before storage (Bearer tokens, JWTs, API keys, emails)
• Configurable IP address privacy (raw, anonymized, or hashed storage)
• Full-text search across all columns
• Plugin-based filtering via dropdown
• Sort by any column (ascending/descending)
• CSV export with progress bar and cancellation support
• View row details in a modal overlay via REST API
• Stack trace display with source file links (ThickBox viewer)
• Table truncate and drop via REST API with core table protection
• Multisite-aware (captures blog_id)
• Slack and Telegram notifications for fatal errors
• Automatic record pruning via configurable retention period

Technology Stack

• PHP 7.4+ (strict types)
• WordPress WP_List_Table API (via Abstract_List)
• WordPress REST API for row detail retrieval, truncate, and drop
• wp-api-fetch for client-side REST calls
• jQuery for modal, clipboard, and share interactions
• ThickBox for source file viewing
• Custom CSV export with batch processing via AJAX
• PHP shutdown function and custom exception handler for error capture

advanced-analytics/
├── classes/
│   ├── vendor/
│   │   ├── lists/
│   │   │   ├── class-fatals-list.php             — WP_List_Table for PHP error data
│   │   │   └── views/
│   │   │       └── class-fatals-view.php          — Page rendering & action handlers
│   │   ├── entities/
│   │   │   └── class-wp-fatals-entity.php         — DB entity, schema, dedup, redaction
│   │   ├── controllers/
│   │   │   └── class-endpoints.php                — REST API route registration
│   │   ├── helpers/
│   │   │   ├── class-wp-error-handler.php         — Error capture (shutdown + exception)
│   │   │   ├── class-settings.php                 — Settings integration
│   │   │   ├── class-ajax-helper.php              — AJAX CSV export handler
│   │   │   └── class-miscellaneous.php            — Admin bar links, page helpers
│   │   └── settings/
│   │       └── settings-options/
│   │           └── fatals-list.php                — Module settings fields
│   └── migration/
│       └── class-migration.php                    — DB migrations (indexes, colors)
└── js/
    └── admin-export-csv.js                        — CSV export with progress & cancellation

UI Components

• Search box — searches across all columns using LIKE %term%
• Plugin filter dropdown — filters errors by source plugin slug
• “CSV Export” button — exports error data with progress bar and cancel option
• Sortable columns — all columns sortable, default sort by datetime DESC
• Row actions — View (modal) | Delete
• Bulk actions — Delete selected records
• View modal — full error detail with copy-to-clipboard and share
• Stack trace — collapsible details with source file links (ThickBox)
• Table metadata bar — size, engine, auto-increment, collation, create/update times
• Severity badges — colored indicators for error severity
• Relative timestamps — “5 minutes ago”, “Yesterday at 3:00 pm”
• User links — clickable links to WordPress user profiles

┌──────────────────────────────────────────────────────────────────────┐
│  PHP errors                                                          │
│──────────────────────────────────────────────────────────────────────│
│  Bulk Actions [▼] [Apply]  [Plugin Filter ▼]  [CSV Export]           │
│  Size: 2.5 MB | Engine: InnoDB | Auto increment: 1542                │
│                                                          [🔍 Search] │
│──────────────────────────────────────────────────────────────────────│
│  ☐ Date ↕       | Severity | Message         | File      | Source    │
│  ☐ 5 min ago    | FATAL    | Call to undef…  | plugin.…  | MyPlugin  │
│     View | Delete                                                    │
│  ☐ 1 hour ago   | WARNING  | Undefined var…  | theme.…   | MyTheme   │
│     View | Delete                                                    │
│──────────────────────────────────────────────────────────────────────│
│  Bulk Actions [▼] [Apply]                            ‹ 1 of 50 ›     │
└──────────────────────────────────────────────────────────────────────┘

Available Settings

Extends Abstract_List (which extends WP_List_Table). Uses List_Trait. Handles the PHP error data admin list rendering, column management, sorting, searching, pagination, plugin filtering, bulk operations, CSV export, and table metadata display.

Constants

<?php
public const PAGE_SLUG            = '{ADVAN_INNER_SLUG}_page_advan_fatals';
public const SCREEN_OPTIONS_SLUG  = 'advanced_analytics_fatals_list';
public const SEARCH_INPUT         = 's';
public const FATALS_MENU_SLUG     = 'advan_fatals';
public const PLUGIN_FILTER_ACTION = self::PAGE_SLUG . '_filter_plugin';
protected const MAX_STACK_TRACE_LINES = 50;

Constructor

<?php
public function __construct( string $table_name = '' )

Initializes Common_Table with the fatals entity table name and calls the parent constructor with plural/singular labels set to the entity table name.

Key Methods

Column Rendering

Handles page rendering for the PHP error list screen, the view modal, and processes form submissions. All methods are static.

Public Static Methods

Modal View (Inline JavaScript)

The View action triggers a REST API call via wp.apiFetch() to retrieve full error data. The response HTML is injected into the modal overlay. The modal also supports:

• Copy to clipboard — copies raw HTML of error data via navigator.clipboard
• Share — uses the navigator.share Web Share API (falls back gracefully)
• Dark skin — reads aadvana-backend-skin from localStorage
• Source file links — ThickBox links open within the modal for viewing source code

Extends Abstract_Entity. Central entity class for all fatals database operations. Handles table creation, schema definition, deduplication, PII redaction, source identification, IP collection, and record preparation. Contains both static and instance methods.

Constants

<?php
// Table name: {prefix}advan_wp_fatals_log
protected static $table = ADVAN_PREFIX . 'wp_fatals_log';

Key Methods

Handles PHP error capture via three entry points. All capture is gated by the fatals_module_enabled setting.

Error Capture Entry Points

Table name: {prefix}advan_wp_fatals_log

Indexes

Capture Flow

1. PHP error occurs (fatal, exception, warning, etc.)
2. WP_Error_Handler captures the error via shutdown function or exception handler
3. WP_Fatals_Entity::prepare_fatality_to_store() is called with error details
4. Message and backtrace are redacted of PII/secrets
5. A normalized hash is generated from the error signature
6. The hash is checked against existing records
7. If a matching hash exists: repeating count is incremented, datetime updated
8. If no match: a new record is inserted with source identification and user context

Deduplication Logic

Errors are deduplicated via SHA-256 hash of a normalized string: message|line|file|backtrace. The normalization process:

• Timestamps are replaced with [TS]
• Line numbers are replaced with line [N]
• Large numbers are replaced with [N]
• Hex values are replaced with 0x[HEX]

This ensures that the same fundamental error with different runtime details (e.g., different timestamps or line numbers from dynamic code) is recognized as a single issue.

prepare_fatality_to_store() identifies error sources in priority order:

Version information is also extracted from the identified source and stored both as human-readable text (version_text) and a sortable integer (version) using the version_to_decimal() encoding scheme (major * 10^12 + minor * 10^6 + patch).

Before any error data is stored in the database, the redact_text() method sanitizes messages and the redact_backtrace() method sanitizes stack traces. The following patterns are redacted:

• Bearer tokens — Bearer ... replaced with Bearer [REDACTED]
• JWT tokens — three-part dot-separated base64 strings
• API keys — common key patterns and variable names containing key, secret, password, token
• Email addresses — replaced with [EMAIL]
• Long hex strings — potential hashes or tokens
• Sensitive URL parameters — passwords, tokens, and keys in query strings

All endpoints are registered under the 0-day/v1 namespace. Every endpoint requires manage_options capability.

View Error Record GET

Truncate Table DELETE

Drop Table DELETE

Admin Post Actions ACTION

WordPress Hooks Used ACTION

Filters FILTER

Settings are on the PHP error Log tab within the main settings page.

<?php
// Check if the PHP Error Tracker module is enabled
$enabled = Settings::get_option( 'fatals_module_enabled' );

Settings Builder Usage

<?php
// How the settings are defined in fatals-list.php
Settings::build_option(
    array(
        'title' => esc_html__( 'PHP errors list options', '0-day-analytics' ),
        'id'    => 'fatals-settings-options',
        'type'  => 'header',
        'hint'  => esc_html__( 'The module captures PHP Fatal Errors...', '0-day-analytics' ),
    )
);

Settings::build_option(
    array(
        'name'    => esc_html__( 'Enable PHP errors list module', '0-day-analytics' ),
        'id'      => 'fatals_module_enabled',
        'type'    => 'checkbox',
        'hint'    => esc_html__( 'If you disable this, the entire plugin fatals module will be disabled...', '0-day-analytics' ),
        'default' => Settings::get_option( 'fatals_module_enabled' ),
    )
);

Admin Columns

Search

The search box filters across all columns using LIKE %term% for each column (OR logic). Query parameter: s

Plugin Filter

A dropdown of plugins that have recorded errors. Filters by source_slug column. Submitted via admin_post handler with nonce verification.

Default Sort

By datetime column in DESC order (newest first).

Pagination

Default items per page: 20. Configurable via Screen Options. Uses LIMIT/OFFSET SQL pagination.

Row Actions

Bulk Actions

Destructive Table Actions (Config Help Tab)

The CSV export functionality is handled via AJAX through Ajax_Helper. When the export type is fatals:

• A new Fatals_List instance is created
• Active search term and plugin filter are passed from the UI
• fetch_table_data() is called with batch pagination
• Data is exported through the shared CSV export pipeline
• The file name includes the fatals table name
• Progress is reported via AJAX callbacks with progress bar and cancel support

Capability Checks

• manage_options enforced on: page rendering, row delete, bulk operations, REST API endpoints, action processing
• Menu visibility: manage_options or read depending on menu_admins_only setting

Nonce Verification

Input Validation

• Plugin slugs — validated with /^[a-zA-Z0-9\-_]{1,255}$/ regex
• Order/orderby — sanitized via esc_sql(), sanitize_text_field(), and allowlisted
• Search terms — escaped via $wpdb->esc_like() and parameterized with %s
• Record IDs — cast to (int) before delete operations
• All displayed values — escaped with esc_html(), esc_attr(), esc_url()

PII Protection

• Error messages redacted of secrets and PII before storage
• Stack traces recursively redacted
• IP addresses support anonymization and hashing modes
• Custom redaction rules via advan_redact_text filter

PHP error codes are mapped to human-readable severity strings by WP_Error_Handler::error_code_to_string():

Uncaught exceptions handled via exception_handler() are always stored with severity FATAL.

WP_Fatals_Entity::collect_all_client_ips() collects client IPs from multiple server headers and supports three configurable storage modes:

Header Sources

By default, the following headers are checked (configurable via advan_ip_header_keys filter):

• HTTP_CF_CONNECTING_IP (Cloudflare)
• HTTP_TRUE_CLIENT_IP
• HTTP_X_FORWARDED_FOR
• HTTP_X_REAL_IP
• HTTP_X_CLUSTER_CLIENT_IP
• HTTP_FORWARDED
• HTTP_X_FORWARDED
• HTTP_CLIENT_IP
• HTTP_FASTLY_CLIENT_IP
• HTTP_AKAMAI_ORIGIN_HOP
• HTTP_X_APPENGINE_USER_IP
• REMOTE_ADDR

Example 1: Check If the Fatals Module Is Enabled

<?php
use ADVAN\Helpers\Settings;

if ( Settings::get_option( 'fatals_module_enabled' ) ) {
    echo 'PHP Error Tracker is active.';
}

Example 2: Query Fatals by Severity

<?php
use ADVAN\Entities\WP_Fatals_Entity;

// Get all FATAL severity records from the last 24 hours
global $wpdb;
$table  = WP_Fatals_Entity::get_table_name();
$since  = time() - DAY_IN_SECONDS;

$fatals = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT id, message, error_file, error_line, source, datetime
         FROM {$table}
         WHERE severity = %s AND datetime > %d
         ORDER BY datetime DESC",
        'FATAL',
        $since
    ),
    ARRAY_A
);

foreach ( $fatals as $fatal ) {
    printf(
        "ID: %d | Source: %s | File: %s:%d\nMessage: %s\n\n",
        $fatal['id'],
        $fatal['source'] ?? 'Unknown',
        $fatal['error_file'],
        $fatal['error_line'],
        $fatal['message']
    );
}

Example 3: Add Custom PII Redaction Rules

<?php
// In your plugin or theme functions.php
add_filter( 'advan_redact_text', function( string $text ): string {
    // Redact custom internal API tokens
    $text = preg_replace(
        '/MYAPP-[A-Za-z0-9]{32}/',
        '[MYAPP-TOKEN-REDACTED]',
        $text
    );
    return $text;
} );

Example 4: Configure IP Anonymization

<?php
// Anonymize all stored IPs (GDPR compliance)
add_filter( 'advan_ip_mode', function() {
    return 'anonymize';
} );

// Or hash them instead
add_filter( 'advan_ip_mode', function() {
    return 'hash';
} );

// Custom hash salt
add_filter( 'advan_ip_hash_salt', function() {
    return 'my-custom-salt-value';
} );

Example 5: Trust Proxy Headers (When Behind a Load Balancer)

<?php
// Enable proxy header trust (only if you control the proxy)
add_filter( 'advan_ip_trust_proxy', '__return_true' );

// Filter private IPs from the collection
add_filter( 'advan_ip_filter_private', '__return_true' );

Example 6: Prune Old Error Records

<?php
use ADVAN\Entities\WP_Fatals_Entity;

// Delete records older than 30 days
$deleted = WP_Fatals_Entity::prune_old_records( 30 );

echo "Pruned {$deleted} old error records.";

Example 7: Get Plugin Filter Dropdown

<?php
use ADVAN\Entities\WP_Fatals_Entity;

// Render a dropdown of plugins that have recorded errors
$selected_plugin = 'my-plugin-slug';
$dropdown_html   = WP_Fatals_Entity::get_all_plugins_dropdown( $selected_plugin );

echo $dropdown_html;

Example 8: Inspect the Fatals Table Schema

<?php
use ADVAN\Entities_Global\Common_Table;
use ADVAN\Entities\WP_Fatals_Entity;

Common_Table::init( WP_Fatals_Entity::get_table_name() );

$columns = Common_Table::get_columns_info();

foreach ( $columns as $col ) {
    printf(
        "Column: %s | Type: %s | Key: %s\n",
        $col['Field'],
        $col['Type'],
        $col['Key']
    );
}

Example 9: Get Fatals Table Health Info

<?php
use ADVAN\Entities_Global\Common_Table;
use ADVAN\Entities\WP_Fatals_Entity;

$info = Common_Table::get_table_info( WP_Fatals_Entity::get_table_name() );

if ( ! is_wp_error( $info ) ) {
    echo 'Row count: ' . $info['health']['row_count'];
    echo 'Data size: ' . size_format( $info['health']['data_size'] );
    echo 'Needs optimization: ' . ( $info['health']['needs_optimization'] ? 'Yes' : 'No' );
}

Example 10: Version Encoding

<?php
use ADVAN\Entities\WP_Fatals_Entity;

// Convert semantic version to sortable integer
$version_int = WP_Fatals_Entity::version_to_decimal( '2.4.1' );
// Result: 2000000004000001

// This allows sorting by version in SQL:
// ORDER BY version DESC