0 Day Analytics

PHP Error Module — User Guide

By sdobreff on · 15 min read · PHP Error · 0-day-analytics, documentation
Table of Contents

The PHP Error Tracker module automatically captures and stores PHP fatal errors, uncaught exceptions, warnings, deprecation notices, and other PHP error types into a dedicated database table. Unlike the standard debug.log file, these records persist across log rotations and are accessible directly from the WordPress admin — even when WP_DEBUG is disabled.

Who is this for?
You need the Administrator role (the manage_options capability) to access the PHP Error Tracker. Other user roles will not see the menu item or be able to perform any operations.

Key Features

  • Automatic capture of PHP fatal errors, exceptions, warnings, and notices
  • Works even when WP_DEBUG is turned off
  • Automatic deduplication — repeated errors increment a counter instead of flooding the log
  • Automatic detection of the error source (plugin, theme, WordPress core, or PHP)
  • Stack trace display with clickable source file links
  • View full error details in a modal overlay
  • Filter errors by plugin
  • Search across all error fields
  • Sort by any column
  • Export error data to CSV
  • Relative timestamps (“5 minutes ago”)
  • PII and secret redaction — sensitive data is automatically masked before storage
  • Configurable IP address privacy (raw, anonymized, or hashed)
  • Severity-based color coding
  • Delete individual or multiple records

Enable / Disable the Module

The PHP Error Tracker is a standalone module that can be enabled or disabled independently of other Advanced Analytics features.

  1. Navigate to Error Logs → Settings in the WordPress admin sidebar.
  2. Click the “PHP error Log” tab (or scroll to the section headed PHP errors list options).
  3. Toggle the “Enable PHP errors list module” checkbox.
  4. Click Save Changes.
wp-admin/admin.php?page=advan_logs_settings
Important: Disabling the module stops all error capture and removes the PHP error viewer sub-menu item. No existing data is lost — the module simply becomes hidden. Re-enabling it restores full access and resumes error capture.

Accessing the Error Tracker

Once the module is enabled, find it in the WordPress admin sidebar:

  1. In the WordPress admin menu, look for the Error Logs main menu.
  2. Click the “PHP error viewer” sub-menu item.
  3. The Error Tracker loads showing all captured PHP errors, sorted by date (newest first).
wp-admin/admin.php?page=advan_fatals

Browsing Error Records

The main view displays captured PHP errors in a paginated, sortable list table (using WordPress’s native WP_List_Table interface). Each row represents a unique error occurrence. Repeated errors are deduplicated and tracked with an occurrence counter.

At a Glance

The error table provides a quick overview of your site’s PHP health:

  • Colored severity indicators — rows are styled based on error severity for quick visual scanning
  • Relative timestamps — “5 minutes ago”, “Yesterday at 3:00 pm” for easy time reference
  • Source identification — instantly see which plugin, theme, or core component caused each error
  • Occurrence counts — the “Number of occurrences” column shows how many times each unique error has been seen

Understanding the Columns

Column Description
Date When the error last occurred. Shows relative time (“5 min ago”) and a full date/time. Row actions (View, Delete) appear below this column.
Severity The type of PHP error: FATAL, WARNING, NOTICE, PARSE, DEPRECATED, etc.
Message The PHP error message. Includes copy/share icons and a “Show details” button to expand the stack trace.
File The PHP file where the error occurred. Clickable link that opens the source file in a viewer.
Source Type Whether the error originated from a plugin, theme, WordPress core, or php itself.
Source The name of the specific plugin, theme, or component that caused the error.
Version The version of the plugin or theme when the error occurred.
Environment The WordPress context: admin, ajax, cron, rest, cli, or frontend.
User The WordPress user who triggered the error (linked to their profile), or “WP System or Anonymous user” for background/unauthenticated requests.
User Role(s) The WordPress role(s) of the user at the time of the error.
IP The client’s IP address (may be anonymized or hashed depending on your settings).
Number of occurrences How many times this exact error has been seen. Higher numbers indicate persistent issues.
From Blog Multisite only. The blog/site ID where the error originated.
Tip: You can show or hide columns via Screen Options in the top-right corner. This is useful for simplifying the view when you don’t need all columns.

Use the Search box on the right side of the table to filter error records.

  1. Enter your search term in the search input field.
  2. Click the Search button.
  3. The table reloads showing only records where any column contains your search term.
  4. To clear the search, remove the text and click Search again.
Note: The search operates across all columns including message, file path, source, severity, and IP. It uses a case-insensitive partial match.

Filtering by Plugin

The plugin filter dropdown lets you quickly narrow down errors to a specific plugin.

  1. Locate the plugin filter dropdown above the table (left side, next to Bulk Actions).
  2. Select a plugin from the dropdown. Only plugins that have recorded errors are listed.
  3. The page reloads showing only errors from the selected plugin.
  4. To reset the filter, select the default option (all plugins) from the dropdown.
Tip: The plugin filter can be combined with the search box. For example, filter by “My Plugin” and search for “database” to find only database-related errors from that specific plugin.

Sorting Columns

All columns in the error table are sortable. Click any column header to toggle the sort order:

  • Click once to sort in ascending order (ASC).
  • Click again to sort in descending order (DESC).

A small arrow indicator appears next to the currently sorted column. By default, errors are sorted by Date in descending order (newest first).

Useful Sorting Examples

  • Sort by Severity — group all FATAL errors together at the top
  • Sort by Number of occurrences — find the most frequently repeated errors
  • Sort by Source — group errors by plugin or theme
  • Sort by Version — identify which version introduced a bug

Pagination & Screen Options

The table displays data in pages. You can configure how many records are shown per page.

  1. Click Screen Options in the top-right corner of the admin page.
  2. Set the “Number of fatals to show” field to your preferred value (default is 20).
  3. Click Apply.

The pagination controls at the top and bottom of the table let you navigate between pages. The total number of records and pages is displayed.

Viewing Error Details

To see the full details of an error record (including all columns and the complete backtrace):

  1. Find the error you want to inspect.
  2. Click the “View” link beneath the Date column value.
  3. A modal overlay opens displaying all error fields in a detail view.
  4. Click the × button or click outside the modal to close it.
  • Full error message — the complete, untruncated error message
  • File and line number — exact location with clickable source file link
  • Complete backtrace — the full stack trace with source file links
  • Copy to clipboard — click the clipboard icon to copy the error details to your clipboard for sharing or bug reports
  • Share — on devices that support the Web Share API, click the share icon to share via your device’s native sharing dialog. The site URL is automatically appended.

Reading Stack Traces

The stack trace (backtrace) shows the sequence of function calls that led to the error. This is essential for debugging.

  1. In the error table, find a record that has a “Show details” button in the Message column.
  2. Click “Show details” to expand the stack trace inline.
  3. The trace shows each function call with the file and line number.
  4. Click any file link in the trace to open that file in the source viewer.

Reading the Trace

Stack traces are displayed in reverse chronological order (most recent call first). Each line shows:

  • Function/method name — in bold italic
  • File path and line number — as a clickable link

Follow the trace from top to bottom to understand the call chain that led to the error. The top-most entry is where the error occurred; entries below show what called it.

Note: Stack traces are limited to 50 lines. If a trace exceeds this limit, a message indicates how many additional lines were truncated.

Viewing Source Files

File paths in the error table and stack traces are clickable links that open the PHP source file in a viewer.

  1. Click any file path link (in the File column or within a stack trace).
  2. A ThickBox popup opens showing the source code of that file.
  3. The viewer highlights the line where the error occurred.
  4. Close the popup by clicking the × button.
Note: The file viewer is read-only. You cannot edit files directly from this interface. Use your code editor or an SFTP client to make changes.

Deleting Records

To delete a single error record:

  1. Find the record you want to remove.
  2. Click the “Delete” link beneath the Date column value.
  3. A confirmation dialog appears: “You sure you want to delete this record?”
  4. Click OK to confirm. The record is permanently removed from the database.
Caution: Deletion is immediate and permanent — there is no trash or undo. The error record and its stack trace data are permanently lost.

Bulk Actions

To delete multiple error records at once:

  1. Check the boxes next to the records you want to delete. Use the top checkbox to select all visible records.
  2. From the Bulk Actions dropdown, select “Delete Records”.
  3. Click Apply.
  4. The selected records are permanently deleted.
Tip: Combine the plugin filter or search with bulk delete to efficiently clean up errors from a specific plugin or matching a specific pattern.

CSV Export

You can export the current error data to a CSV file for offline analysis, reporting, or sharing with developers.

  1. Optionally apply a search filter or plugin filter to narrow down the records.
  2. Click the “CSV Export” button (located above the table, on the right side of the Bulk Actions area).
  3. A progress bar appears showing export progress.
  4. Once complete, the CSV file downloads automatically.
Note: The export respects any active search or plugin filter. Use the Cancel button to abort long-running exports. The exported file name includes the error table name for easy identification.

Table Metadata Bar

Below the main table controls, a metadata bar displays key information about the error log table:

  • Size — Total size of the error log table on disk
  • Engine — Database engine (typically InnoDB)
  • Auto increment — Next auto-increment ID value
  • Collation — Character set collation
  • Create time — When the table was first created
  • Update time — When the table was last modified

This information helps you monitor the growth of your error log and understand the table’s health at a glance.

Truncating the Error Table

Truncating removes all error records from the table but keeps the table structure intact. This is useful for clearing out old errors and starting fresh.

  1. Open the Help tab from Screen Options and navigate to the “Config” panel.
  2. Click the “Truncate Table” button.
  3. A confirmation message appears: “You sure you want to truncate this table? That operation is destructive”
  4. Click OK to proceed. The page reloads with an empty error table.
Danger — Destructive Operation: Truncating is irreversible. All error records, stack traces, and occurrence counts are permanently deleted. The table structure remains, and new errors will continue to be captured.

Dropping the Error Table

Dropping permanently deletes the error table and all its data from the database.

  1. Open the Help tab from Screen Options and navigate to the “Config” panel.
  2. Click the “Drop Table” button.
  3. A confirmation message appears: “You sure you want to delete this table? That operation is destructive”
  4. Click OK to proceed. The table is permanently removed.
Danger — Destructive Operation: Dropping the table removes it entirely from the database. The table will be re-created the next time the plugin needs it, but all historical error data will be lost.

Severity Levels

The PHP Error Tracker captures various types of PHP errors. Understanding the severity levels helps you prioritize which errors to address first.

Severity Priority Description
FATAL Critical A fatal error or uncaught exception that stopped PHP execution. These should be fixed immediately as they typically cause a white screen or broken functionality.
PARSE Critical A syntax error in the PHP code. The file cannot be executed at all.
CORE ERROR Critical A fatal error during PHP startup. Usually indicates server misconfiguration.
COMPILE ERROR Critical An error during compilation. Similar in impact to PARSE errors.
RECOVERABLE ERROR High A catchable fatal error. The script can potentially continue if handled, but the situation is dangerous.
WARNING Medium A non-fatal runtime warning. PHP continues executing, but the warning may indicate a real problem (e.g., missing file, wrong parameter type).
USER ERROR Medium A custom error raised by code via trigger_error() with E_USER_ERROR.
USER WARNING Medium A custom warning raised by code via trigger_error().
NOTICE Low An informational notice. Usually indicates code that may not work as intended (undefined variables, missing array keys).
DEPRECATED Low A function or feature that is deprecated and will be removed in a future PHP or WordPress version. Plan to update the affected code.
STRICT Low Suggestions for improving code quality and forward compatibility.
USER NOTICE / USER DEPRECATED Low Custom notices or deprecations raised by code.
Tip: Focus on FATAL and PARSE errors first — these are the ones that break your site. Warnings and deprecations should be addressed in priority order during regular maintenance.

How Deduplication Works

The PHP Error Tracker automatically deduplicates identical errors. Instead of creating a new row every time the same error occurs, it recognizes the error as a repeat and increments the “Number of occurrences” counter.

How It Works

  • When an error is captured, a unique fingerprint (hash) is generated from the error message, file, line number, and stack trace.
  • Dynamic parts of the error (timestamps, specific numbers, etc.) are normalized so that the “same” error with different runtime values is still recognized as identical.
  • If a matching fingerprint already exists in the database, the occurrence counter is incremented and the timestamp is updated to the latest occurrence.
  • If no match is found, a new record is created.

This means you can easily identify the most persistent problems by sorting by the “Number of occurrences” column.

Privacy & PII Redaction

The PHP Error Tracker is designed with privacy in mind. Sensitive data is automatically redacted before errors are stored in the database.

What Gets Redacted

  • API keys and tokens — Bearer tokens, JWTs, and any values in variables named key, secret, password, or token
  • Email addresses — replaced with [EMAIL]
  • Long hex strings — potential hashes or secret tokens
  • Sensitive URL parameters — passwords, tokens, and keys in query strings

IP Address Privacy

IP addresses can be stored in one of three modes, configurable via WordPress filters:

  • Raw (default) — IPs stored as-is
  • Anonymized — last octet zeroed (e.g., 192.168.1.0 instead of 192.168.1.42)
  • Hashed — IP replaced with a one-way hash for correlation without revealing the actual address
GDPR Note: For GDPR compliance, consider enabling IP anonymization or hashing. Consult your data protection officer for guidance specific to your jurisdiction.

Help Tabs

The PHP Error Tracker provides contextual help via the WordPress Screen Options → Help tab at the top of the page. Two panels are available:

Help Panel

  • Overview of the PHP Error Tracker functionality.
  • Instructions for filtering, searching, and deleting records.
  • Notes on bulk operations and destructive actions.

Config Panel

  • Table metadata: name, engine, version, creation time, collation.
  • Truncate Table button for clearing all error records.
  • Drop Table button for permanently removing the error table.

Multisite Networks

The PHP Error Tracker is fully multisite-aware:

  • Each error record includes a “From Blog” column showing which site in the network generated the error.
  • The plugin filter dropdown and search work across the entire network’s error records.
  • The plugin filter correctly handles network admin vs. site admin context for proper URL generation.

Troubleshooting

PHP Error Viewer menu item is not visible

  • Ensure the PHP errors module is enabled in Settings → PHP error Log tab.
  • Verify you are logged in with the Administrator role (or have the manage_options capability).
  • Check if the menu_admins_only setting is enabled — when enabled, only users with manage_options can see the menu.

No errors are being captured

  • Confirm the fatals_module_enabled setting is turned on.
  • Ensure the plugin’s error handler is properly loaded. Check that no other plugin is intercepting PHP errors before Advanced Analytics can capture them.
  • If using a caching or security plugin that modifies PHP error handling, check for conflicts.
  • Verify the fatals database table exists. If it was dropped, the plugin will re-create it automatically.

Error records show “Unknown” source

  • This occurs when the error file path cannot be matched to a known plugin, theme, or WordPress core directory.
  • Custom PHP files outside the standard WordPress directory structure will be categorized as source type “php” with source “PHP”.

The error table is growing very large

  • Use the plugin filter and bulk delete to clean up old, resolved errors.
  • Consider truncating the table periodically (via the Config help tab).
  • Automatic record pruning is available and can be configured for a retention period (default: 90 days).
  • Fix the underlying errors to prevent new records from being created.

Source file viewer does not open

  • Ensure ThickBox is properly loaded. Try hard-refreshing the page (Ctrl+Shift+R).
  • Check for JavaScript errors in the browser console that may prevent the ThickBox from opening.
  • Some security plugins may block the ThickBox AJAX requests. Check your security plugin’s settings.

CSV export is slow or fails

  • Large error logs may take longer to export. The progress bar shows real-time export status.
  • Use the Cancel button to abort if needed.
  • Apply a search filter or plugin filter to reduce the number of exported records.

IP addresses show as hashes or truncated values

  • IP anonymization or hashing may be enabled via WordPress filters. Check with your site administrator or developer.
  • If you need raw IPs (e.g., for security investigation), ensure the advan_ip_mode filter is set to 'raw'.
Need developer documentation?
See PHP Error Module Developer Documentation for architectural details, class references, REST API endpoints, and code examples for extending the PHP Error module programmatically.
← How to Create a Slack App, Get Bot Token & Channel ID (Complete Guide) 0 Day Analytics – PHP Error Module Developer Documentation →
Share this page
Back to top