Troubleshooting

Common issues and solutions for WPZylos Requirements.

Requirements Not Being Checked

Symptom

Plugin activates without checking requirements.

Cause

Service provider not registered, or registered in wrong order.

Solution

1. Ensure RequirementsServiceProvider is registered first:

// bootstrap/app.php
$app->register(RequirementsServiceProvider::class);  // FIRST
$app->register(OtherServiceProvider::class);         // After

2. Verify config file exists:

ls config/requirements.php

3. Check config file returns an array:

<?php
return [
    'min_php_version' => '8.0',
];  // Must return array

Plugin Slug Not Found

Symptom

Required plugin WooCommerce is missing.

Cause

Wrong plugin slug format.

Solution

Find the correct slug in WordPress plugins directory:

wp-content/plugins/
+-- woocommerce/
|   +-- woocommerce.php     ← Slug: woocommerce/woocommerce.php
+-- jetpack/
|   +-- jetpack.php         ← Slug: jetpack/jetpack.php
+-- akismet/
    +-- akismet.php         ← Slug: akismet/akismet.php

Use this format:

'required_plugins' => [
    'WooCommerce' => [
        'plugin_slug' => 'woocommerce/woocommerce.php',  // folder/file.php
    ],
],

"WooCommerce is not active"

Symptom

Plugin reports WooCommerce is not active, but it is.

Cause

Requirements checked before WooCommerce is loaded.

Solution

Ensure your plugin loads after required plugins. In your main plugin file:

// Don't load until plugins_loaded hook
add_action('plugins_loaded', function() {
    require_once __DIR__ . '/bootstrap/app.php';
}, 5);  // Low priority

Or use is_plugin_active directly:

// In requirements check
if (!function_exists('is_plugin_active')) {
    require_once ABSPATH . 'wp-admin/includes/plugin.php';
}

Config File Not Found

Symptom

No requirements are checked, empty checker.

Solution

1. Check path in service provider:

// RequirementsServiceProvider checks:
// config/requirements.php (via context)

2. Verify your plugin context returns correct config path:

$context->path('config/requirements.php');

3. Create the config file:

mkdir -p config
touch config/requirements.php

Translation Strings Not Working

Symptom

Error messages show translation keys instead of text.

Cause

Wrong text domain.

Solution

Match text domain in config:

// When using RequirementsConfig
$checker = RequirementsConfig::fromFile($path, 'your-text-domain');

Ensure text domain matches your plugin's:

// plugin.php header
/**
 * Text Domain: your-text-domain
 */

Admin Notice Not Showing

Symptom

Plugin deactivates but no error notice appears.

Cause

admin_notices hook not fired yet.

Solution

The notice is registered on admin_notices. If you're checking requirements before WordPress admin loads:

// Ensure you're in admin context
if (!is_admin()) {
    return;
}

// Check requirements
$handler->handle(true);

For activation errors, wp_die() is used instead of the notice.

"Class not found" Errors

Symptom

Class 'WPZylos\Framework\Requirements\RequirementsChecker' not found

Cause

Autoloader not loaded or package not installed.

Solution

1. Install the package:

composer require KYNetCode/wpzylos-requirements

2. Load autoloader in plugin.php:

require_once __DIR__ . '/vendor/autoload.php';

3. Run composer dump-autoload:

composer dump-autoload

PHPStan/PHPUnit Errors

Symptom

Function is_plugin_active not found

Cause

WordPress functions not available during static analysis/tests.

Solution

For PHPStan, add to phpstan.neon:

parameters:
  ignoreErrors:
    - "#Function is_plugin_active not found#"

For PHPUnit, use the test bootstrap:

// tests/bootstrap.php
if (!function_exists('is_plugin_active')) {
    function is_plugin_active(string $plugin): bool {
        return false;
    }
}

Memory Issues with Many Requirements

Symptom

High memory usage when checking many requirements.

Solution

Requirements are checked lazily. If you're checking hundreds of requirements, consider:

1. Only check critical requirements at activation
2. Check non-critical requirements at runtime
3. Cache results in transients

$cached = get_transient('my_plugin_requirements');
if ($cached === false) {
    $checker->check();
    set_transient('my_plugin_requirements', $checker->hasFailures(), HOUR_IN_SECONDS);
}

Still Having Issues?

1. Enable WordPress debug mode:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

2. Check debug.log for errors:

tail -f wp-content/debug.log

3. Open an issue: GitHub Issues