PHPackages                             nhrrob/wp-fatal-tester - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. nhrrob/wp-fatal-tester

ActiveLibrary[Testing & Quality](/categories/testing)

nhrrob/wp-fatal-tester
======================

A comprehensive CLI tool to detect fatal PHP errors and compatibility issues in WordPress plugins and themes

v1.3.1(8mo ago)5141MITPHPPHP >=7.4

Since Aug 17Pushed 8mo agoCompare

[ Source](https://github.com/nhrrob/wp-fatal-tester)[ Packagist](https://packagist.org/packages/nhrrob/wp-fatal-tester)[ Docs](https://github.com/nhrrob/wp-fatal-tester)[ RSS](/packages/nhrrob-wp-fatal-tester/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (4)Dependencies (1)Versions (8)Used By (0)

WordPress Fatal Error Tester
============================

[](#wordpress-fatal-error-tester)

A comprehensive CLI tool to detect fatal PHP errors and compatibility issues in WordPress plugins and themes. This tool helps developers identify potential fatal errors before deploying to production by testing code against different PHP and WordPress version combinations.

Features
--------

[](#features)

### 🔍 **Comprehensive Error Detection**

[](#-comprehensive-error-detection)

- **Syntax Errors**: Detects PHP syntax errors, missing semicolons, and bracket mismatches
- **Undefined Functions**: Identifies calls to undefined or removed functions
- **Class Conflicts**: Detects class redeclaration and undefined class usage
- **PHP Version Compatibility**: Tests against PHP 7.4, 8.0, 8.1, 8.2, and 8.3
- **WordPress Compatibility**: Tests against WordPress 6.0+ versions
- **Deprecated Features**: Warns about deprecated PHP and WordPress functions

### 📊 **Detailed Reporting**

[](#-detailed-reporting)

- Color-coded error output with severity levels
- File location and line number information
- Contextual suggestions for fixing errors
- Comprehensive summary reports
- Version compatibility matrix

### ⚡ **Smart Analysis**

[](#-smart-analysis)

- Scans PHP files recursively
- Excludes common non-essential directories (node\_modules, vendor, tests)
- Detects WordPress-specific patterns and functions
- Identifies version-specific syntax and features

### 🎯 **Widget Exclusion System** (New!)

[](#-widget-exclusion-system-new)

- **Reduces False Positives**: Smart exclusion of widgets without "Load More" functionality
- **AJAX Context Awareness**: Detects template method context issues in AJAX operations
- **Future-Proof Design**: Temporary exclusions with review dates for evolving widgets
- **Multiple Reporting Modes**: Fatal-only, all-errors, and debug modes
- **Configurable Rules**: JSON-based configuration for easy customization
- **CLI Integration**: Command-line options for quick adjustments

Installation
------------

[](#installation)

```
composer require --dev nhrrob/wp-fatal-tester
```

Usage
-----

[](#usage)

### Basic Usage

[](#basic-usage)

Test the current directory (auto-detects plugin name, shows fatal errors only):

```
vendor/bin/fataltest
```

Test a specific plugin (shows fatal errors only):

```
vendor/bin/fataltest my-plugin
```

Show all errors including warnings:

```
vendor/bin/fataltest --show-all-errors
```

### Plugin Name Parameter

[](#plugin-name-parameter)

The plugin name parameter is **optional** when running the tool from within a WordPress plugin directory. The tool will automatically detect the current plugin name based on the directory structure. You only need to specify a plugin name when:

- Running from outside the plugin directory
- Testing a plugin located in a different path
- Overriding the auto-detected plugin name

### Command Line Options

[](#command-line-options)

```
# Show help
vendor/bin/fataltest --help

# Test with all error types (including warnings)
vendor/bin/fataltest my-plugin --show-all-errors

# Test specific PHP and WordPress versions
vendor/bin/fataltest my-plugin --php 8.0,8.1,8.2 --wp 6.3,6.4,6.5,6.6

# Custom severity filtering
vendor/bin/fataltest my-plugin --severity error,warning

# Disable colored output
vendor/bin/fataltest my-plugin --no-colors
```

### What It Tests

[](#what-it-tests)

The tool automatically tests your code against **all major PHP and WordPress versions**:

- **PHP Versions**: 7.4, 8.0, 8.1, 8.2, 8.3 (configurable via `--php` option)
- **WordPress Versions**: 6.3, 6.4, 6.5, 6.6 (configurable via `--wp` option)

This comprehensive testing matrix ensures your plugin works across **20 different environment combinations** by default, providing maximum compatibility coverage for WordPress plugins.

### Default Behavior

[](#default-behavior)

**By default, the tool shows only fatal errors** to focus on critical issues that will break plugin functionality. This filtering approach helps developers concentrate on the most important issues first.

- **Fatal errors** (severity: `error`) are issues that will prevent your plugin from working
- **Warnings** (severity: `warning`) are about deprecated features or potential future issues

Use `--show-all-errors` to see warnings and other non-fatal issues when needed.

### Widget Exclusion System

[](#widget-exclusion-system)

The tool now includes a sophisticated widget exclusion system to reduce false positives, especially for AJAX "Load More" operations:

```
# Default behavior - automatically excludes widgets without load more functionality
vendor/bin/fataltest my-plugin

# Show all errors including excluded ones for debugging
vendor/bin/fataltest my-plugin --widget-reporting-mode all_errors

# Debug widget exclusion decisions
vendor/bin/fataltest my-plugin --debug-widget-exclusions

# Use custom widget configuration
vendor/bin/fataltest my-plugin --widget-config-file ./my-config.json

# Show exclusion statistics
vendor/bin/fataltest my-plugin --show-exclusion-stats
```

**Quick Start**: If you're seeing many false positives from Elementor widgets, see `QUICK_START_WIDGET_EXCLUSIONS.md` for immediate solutions.

### Tested with Essential Addons for Elementor

[](#tested-with-essential-addons-for-elementor)

wp-fatal-tester has been extensively tested with the **Essential Addons for Elementor** free plugin and passes all compatibility tests across PHP 7.4-8.3 and WordPress 6.3-6.6. The tool includes smart ecosystem detection to prevent false positives for Elementor and WooCommerce dependencies.

See `EA_TESTING_GUIDE.md` for detailed testing instructions and integration examples.

### Example Output

[](#example-output)

When you run `vendor/bin/fataltest` from within your plugin directory:

```
🚀 Running fatal test for plugin: my-awesome-plugin
   PHP versions: 7.4, 8.0, 8.1, 8.2, 8.3
   WP versions: 6.3, 6.4, 6.5, 6.6
   Plugin path: /path/to/my-awesome-plugin
   Filter: Fatal errors only (use --show-all-errors to see warnings)

▶️ Testing my-awesome-plugin on PHP 7.4, WP 6.3 (1/20)...
❌ Found 2 error(s) on PHP 8.1, WP 6.5 (15,847 total, filtered by severity)

📋 SYNTAX_ERROR (1 error(s)):
🔴 syntax error, unexpected identifier "create_function"
  Location: plugin.php:25
  💡 Suggestion: Fix the syntax error in the specified line

📋 REMOVED_PHP_FEATURE (1 error(s)):
🔴 create_function() was removed in PHP 8.0.0
  Location: plugin.php:25
  💡 Suggestion: Use anonymous functions instead

# Note: DEPRECATED_PHP_FEATURE warnings and undefined WordPress functions
# are filtered out by default. Use --show-all-errors to see them.

```

**Notice**: The example shows "15,847 total" errors but only 2 fatal errors are displayed. This demonstrates how the filtering helps you focus on critical issues while the high total count reflects WordPress function dependencies.

### Quick Start Tips

[](#quick-start-tips)

1. **Install in your plugin directory**: `composer require --dev nhrrob/wp-fatal-tester`
2. **Run from plugin root**: `vendor/bin/fataltest` (no plugin name needed)
3. **Focus on fatal errors first**: The default output shows only critical issues
4. **Don't worry about high error counts**: Thousands of errors are normal due to WordPress dependencies
5. **Use `--show-all-errors` sparingly**: Only when you need to see warnings and deprecated features

Error Types Detected
--------------------

[](#error-types-detected)

### 🔴 **Fatal Errors (Must Fix)**

[](#-fatal-errors-must-fix)

- **SYNTAX\_ERROR**: PHP syntax errors that prevent code execution
- **UNDEFINED\_FUNCTION**: Calls to functions that don't exist
- **UNDEFINED\_CLASS**: Usage of classes that aren't defined
- **REMOVED\_PHP\_FEATURE**: Features removed in target PHP versions
- **VERSION\_REQUIREMENT**: Features requiring newer PHP/WordPress versions

### 🟡 **Warnings (Should Fix)**

[](#-warnings-should-fix)

- **DEPRECATED\_PHP\_FEATURE**: PHP features deprecated in target versions
- **DEPRECATED\_FUNCTION**: WordPress functions deprecated in target versions
- **DEPRECATED\_HOOK**: WordPress hooks deprecated in target versions
- **MISSING\_SEMICOLON**: Potential missing semicolons
- **UNMATCHED\_BRACKETS**: Potential bracket mismatches

Supported Versions
------------------

[](#supported-versions)

### PHP Versions

[](#php-versions)

- ✅ PHP 7.4+
- ✅ PHP 8.0
- ✅ PHP 8.1
- ✅ PHP 8.2
- ✅ PHP 8.3

### WordPress Versions

[](#wordpress-versions)

- ✅ WordPress 6.0+
- ✅ WordPress 6.1
- ✅ WordPress 6.2
- ✅ WordPress 6.3
- ✅ WordPress 6.4
- ✅ WordPress 6.5
- ✅ WordPress 6.6

Architecture
------------

[](#architecture)

The tool is built with a modular architecture:

### Core Components

[](#core-components)

- **FatalTester**: Main orchestrator class
- **FileScanner**: Scans and filters PHP files
- **ErrorReporter**: Formats and displays results

### Error Detectors

[](#error-detectors)

- **SyntaxErrorDetector**: PHP syntax validation
- **UndefinedFunctionDetector**: Function existence checking
- **ClassConflictDetector**: Class definition validation
- **PHPVersionCompatibilityDetector**: PHP version compatibility
- **WordPressCompatibilityDetector**: WordPress compatibility

Contributing
------------

[](#contributing)

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License
-------

[](#license)

MIT License - see LICENSE file for details.

Changelog
---------

[](#changelog)

### v1.0.0

[](#v100)

- ✅ Complete rewrite with comprehensive error detection
- ✅ PHP 7.4+ and WordPress 6.0+ support
- ✅ Multi-version compatibility testing
- ✅ Detailed error reporting with suggestions
- ✅ Smart file scanning and filtering
- ✅ Color-coded terminal output

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance61

Regular maintenance activity

Popularity11

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~5 days

Total

5

Last Release

246d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/df1895ff781cb81a3a78b2d6cf070be0c125e1f9fc667644fc3706d1ba0fc5a4?d=identicon)[nhrrob](/maintainers/nhrrob)

---

Top Contributors

[![nhrrob](https://avatars.githubusercontent.com/u/7073431?v=4)](https://github.com/nhrrob "nhrrob (34 commits)")

---

Tags

compatibilityphpplugintestingcliwordpressthemefatal-errors

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/nhrrob-wp-fatal-tester/health.svg)

```
[![Health](https://phpackages.com/badges/nhrrob-wp-fatal-tester/health.svg)](https://phpackages.com/packages/nhrrob-wp-fatal-tester)
```

###  Alternatives

[zoon/puphpeteer

A Puppeteer bridge for PHP, supporting the entire API.

204192.9k1](/packages/zoon-puphpeteer)[doppiogancio/mocked-client

A simple way to mock a client

2174.9k3](/packages/doppiogancio-mocked-client)[alleyinteractive/pest-plugin-wordpress

WordPress Pest Integration

263.7k1](/packages/alleyinteractive-pest-plugin-wordpress)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)