Usage

Core patterns for using WPZylos Requirements.

Service Provider Pattern

The recommended approach is using the service provider:

// bootstrap/app.php
use WPZylos\Framework\Requirements\RequirementsServiceProvider;

$app->register(RequirementsServiceProvider::class);

This automatically:

1. Loads config/requirements.php
2. Validates all requirements on boot
3. Shows admin notices for failures
4. Deactivates plugin if requirements fail

Config-Based Validation

From File

use WPZylos\Framework\Requirements\RequirementsConfig;

$checker = RequirementsConfig::fromFile(
    __DIR__ . '/config/requirements.php',
    'my-plugin' // text domain for translations
);

if ($checker->hasFailures()) {
    foreach ($checker->getErrors() as $error) {
        echo $error . "\n";
    }
}

From Array

use WPZylos\Framework\Requirements\RequirementsConfig;

$config = [
    'min_php_version' => '8.1',
    'min_wp_version'  => '6.0',
    'php_extensions'  => ['json', 'mbstring'],
];

$checker = RequirementsConfig::fromArray($config, 'my-plugin');

Programmatic Validation

For fine-grained control, build the checker manually:

use WPZylos\Framework\Requirements\RequirementsChecker;
use WPZylos\Framework\Requirements\Requirements\PhpVersionRequirement;
use WPZylos\Framework\Requirements\Requirements\WordPressVersionRequirement;
use WPZylos\Framework\Requirements\Requirements\PhpExtensionRequirement;
use WPZylos\Framework\Requirements\Requirements\PluginRequirement;
use WPZylos\Framework\Requirements\Requirements\MultisiteRequirement;

$checker = new RequirementsChecker();

// Add requirements with method chaining
$checker
    ->addRequirement(new PhpVersionRequirement('8.1'))
    ->addRequirement(new WordPressVersionRequirement('6.0'))
    ->addRequirement(new PhpExtensionRequirement('json'))
    ->addRequirement(new PhpExtensionRequirement('mbstring'))
    ->addRequirement(new PluginRequirement(
        'WooCommerce',
        'woocommerce/woocommerce.php',
        '8.0.0'
    ))
    ->addRequirement(new MultisiteRequirement(true));

// Run validation
$checker->check();

// Check results
if ($checker->hasFailures()) {
    $errors = $checker->getErrors();
    $failed = $checker->getFailedRequirements();
}

Error Handling

Automatic (Service Provider)

The service provider handles errors automatically:

// RequirementsServiceProvider handles this internally:
// 1. Deactivates plugin
// 2. Shows admin notice
// 3. If activating: wp_die with styled error page

Manual Error Handling

use WPZylos\Framework\Requirements\RequirementsErrorHandler;

$handler = new RequirementsErrorHandler(
    $checker->getErrors(),
    __FILE__,           // plugin file for deactivation
    'My Plugin',        // plugin name for display
    'my-plugin'         // text domain
);

// Handle errors (deactivate = true)
$handler->handle(true);

// Or just render admin notice
$handler->renderAdminNotice();

Custom Requirements

Create custom requirements by implementing RequirementInterface:

use WPZylos\Framework\Requirements\Contracts\RequirementInterface;

class DatabaseVersionRequirement implements RequirementInterface
{
    private string $requiredVersion;
    private string $textDomain;

    public function __construct(string $requiredVersion, string $textDomain = 'wpzylos')
    {
        $this->requiredVersion = $requiredVersion;
        $this->textDomain = $textDomain;
    }

    public function isSatisfied(): bool
    {
        global $wpdb;
        $dbVersion = $wpdb->db_version();
        return version_compare($dbVersion, $this->requiredVersion, '>=');
    }

    public function getErrorMessage(): string
    {
        global $wpdb;
        return sprintf(
            __('MySQL %s+ is required. You are running: %s', $this->textDomain),
            $this->requiredVersion,
            $wpdb->db_version()
        );
    }

    public function getName(): string
    {
        return 'database_version';
    }
}

// Usage
$checker->addRequirement(new DatabaseVersionRequirement('5.7'));

Early Exit Pattern

Stop plugin loading if requirements fail:

// plugin.php
use WPZylos\Framework\Requirements\RequirementsConfig;

$checker = RequirementsConfig::fromFile(__DIR__ . '/config/requirements.php');

if ($checker->hasFailures()) {
    // Show admin notice only
    add_action('admin_notices', function() use ($checker) {
        echo '<div class="notice notice-error">';
        echo '<p><strong>Plugin Requirements Not Met:</strong></p>';
        echo '<ul>';
        foreach ($checker->getErrors() as $error) {
            echo '<li>' . wp_kses_post($error) . '</li>';
        }
        echo '</ul>';
        echo '</div>';
    });
    return; // Stop loading plugin
}

// Continue with plugin bootstrap
require __DIR__ . '/bootstrap/app.php';