Overview
Architecture and design of the WPZylos Requirements package.
Purpose
The Requirements package provides a structured way to validate that your WordPress plugin's environment meets all necessary criteria before activation and during runtime.
Architecture
┌─────────────────────────────────────────────────────────────────┐
| RequirementsServiceProvider |
| ┌───────────────────────────────────────────────────────────┐ |
| | register() | |
| | +-- Loads config/requirements.php | |
| | +-- Creates RequirementsChecker singleton | |
| | | |
| | boot() | |
| | +-- Runs RequirementsChecker->check() | |
| | +-- If failures: RequirementsErrorHandler->handle() | |
| +--─────────────────────────────────────────────────────────┘ |
+--───────────────────────────────────────────────────────────────┘
|
▼
┌─────────────────────────────────────────────────────────────────┐
| RequirementsChecker |
| ┌───────────────────────────────────────────────────────────┐ |
| | Requirements Collection | |
| | +-- PhpVersionRequirement | |
| | +-- WordPressVersionRequirement | |
| | +-- PhpExtensionRequirement[] | |
| | +-- PluginRequirement[] | |
| | +-- MultisiteRequirement | |
| +--─────────────────────────────────────────────────────────┘ |
| |
| check() → Iterates all requirements |
| hasFailures() → Returns boolean |
| getErrors() → Returns error messages |
+--───────────────────────────────────────────────────────────────┘
|
▼
┌─────────────────────────────────────────────────────────────────┐
| RequirementsErrorHandler |
| ┌───────────────────────────────────────────────────────────┐ |
| | handle() | |
| | +-- Deactivate plugin (optional) | |
| | +-- Register admin notice | |
| | +-- If activating: wp_die() with error page | |
| +--─────────────────────────────────────────────────────────┘ |
+--───────────────────────────────────────────────────────────────┘
Requirement Interface
All requirements implement RequirementInterface:
interface RequirementInterface
{
/**
* Check if the requirement is satisfied.
*/
public function isSatisfied(): bool;
/**
* Get the error message when not satisfied.
*/
public function getErrorMessage(): string;
/**
* Get a unique identifier for this requirement.
*/
public function getName(): string;
}
Flow Diagram
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
| Plugin |────▶| Service |────▶| Checker |
| Activation | | Provider | | Validates |
+--────────────┘ +--────────────┘ +--────────────┘
|
▼
┌──────────────┐
| All Pass? |
+--────────────┘
| |
Yes No
| |
▼ ▼
┌──────────┐ ┌──────────────┐
| Plugin | | Error |
| Boots | | Handler |
+--────────┘ +--────────────┘
|
▼
┌──────────────┐
| Deactivate |
| + Notice |
+--────────────┘
Design Principles
1. Fail Fast
Requirements are checked immediately on plugin activation, preventing runtime errors.
2. User-Friendly
Error messages are clear and actionable, telling users exactly what needs to be done.
3. Non-Destructive
Failed requirements deactivate the plugin but don't break the WordPress installation.
4. Extensible
Create custom requirements by implementing RequirementInterface.
File Structure
wpzylos-requirements/
+-- src/
| +-- Contracts/
| | +-- RequirementInterface.php
| | +-- RequirementsCheckerInterface.php
| +-- Requirements/
| | +-- PhpVersionRequirement.php
| | +-- WordPressVersionRequirement.php
| | +-- PhpExtensionRequirement.php
| | +-- PluginRequirement.php
| | +-- MultisiteRequirement.php
| +-- RequirementsChecker.php
| +-- RequirementsConfig.php
| +-- RequirementsErrorHandler.php
| +-- RequirementsServiceProvider.php
+-- stubs/
| +-- requirements.php.stub
+-- tests/
+-- Unit/
+-- RequirementsCheckerTest.php