README

ℹ️ 关于 WP Diagnostics

WP Diagnostics是一个用于处理WordPress插件中最小系统需求检测的实用库。

✨ 优点

1. 验证PHP版本、WordPress版本、激活插件、PHP扩展、类存在性或使用自定义回调。
2. 支持自定义需求验证器。

✅ 要求

1. PHP 7.2或更高。
2. Composer

📖 使用方法

1. 安装

composer require alessandrotesoro/wp-diagnostics

2. 基本用法

1. 创建一个Sematico\Diagnostics\Runner实例。
2. 使用addCheck方法添加检查。
3. 使用satisfied方法验证是否满足要求。
4. 如果未满足要求，使用printNotice方法显示管理员通知。

示例:

<?php

use Sematico\Diagnostics\Check\PHPVersion;
use Sematico\Diagnostics\Check\WPVersion;
use Sematico\Diagnostics\Runner;

defined( 'ABSPATH' ) || exit;

if ( file_exists( dirname( __FILE__ ) . '/vendor/autoload.php' ) ) {
	require dirname( __FILE__ ) . '/vendor/autoload.php';
}

$requirements = new Runner(
	__FILE__,
	'My plugin',
	[
		new WPVersion( '5.7' ),
		new PHPVersion( '7.2' ),
	]
);

if ( ! $requirements->satisfied() ) {
	$requirements->printNotice();
	return;
}

// Now that requirements are met, you can boot your plugin.

在上面的示例中，我们通过传递插件的入口文件路径、插件标题和要验证的检查数组来创建一个Runner实例。

3. 显示管理员通知

当插件的 requirement 未满足时，您可以使用printNotice方法在管理员面板中显示错误消息并自动禁用插件。通知将包含所有错误。

if ( ! $requirements->satisfied() ) {
	$requirements->printNotice();
	return;
}

4. 设置插件的名称

在创建Runner实例时，第二个参数接受一个字符串，该字符串用作插件名称。名称用于在未满足 requirement 时显示的错误通知中。

$requirements = new Runner(
	__FILE__,
	'My plugin'
);

5. 检查配置

Runner实例的第三个参数接受一个包含所有插件所需检查实例的数组。

$requirements = new Runner(
	__FILE__,
	'My plugin',
	[
		new WPVersion( '5.7' ),
		new PHPVersion( '7.2' ),
	]
);

在上面的示例中，我们验证WordPress至少运行版本5.7，php版本至少为7.2。

或者，您可以使用addCheck方法添加检查。

$requirements->addCheck( new WPVersion( '5.7' ) );

6. 在首次失败时停止执行

在某些情况下，您可能希望在出现第一个错误时停止检查验证过程。要启用此功能，只需将第四个参数设置为"true"。或者，您可以使用setBreakOnFailure方法。

$requirements = new Runner(
	__FILE__,
	'My plugin',
	[
		new WPVersion( '5.7' ),
		new PHPVersion( '7.2' ),
	],
	true
);

或者，您可以使用setBreakOnFailure方法。

$requirements->setBreakOnFailure( true );

7. 消息定制

默认情况下，该库不提供国际化支持。如果您希望自定义默认消息或添加翻译支持，您可以使用setMessages方法并覆盖库使用的任何或所有消息。

$requirements->setMessages( [
	'title' => __( 'The “%1$s” plugin could not be activated.', 'my-plugin-textdomain' )
] );

在上面的示例中，我们替换了一个字符串并添加了翻译支持。

您可以通过检查Runner.php文件中的getDefaultMessages方法来找到默认字符串的完整列表。

📖 可用检查

1. 回调

运行一个函数并使用其返回值作为结果。

为了通过检查，您必须返回一个布尔值true。要失败检查，您必须返回一个WP_Error实例。

$check1 = new Callback(
	function() {
		return true;
	}
);

$check2 = new Callback(
	function() {
		return new WP_Error( 'example', 'Your error message goes here' );
	}
);

$requirements->addChecks( [ $check1, $check2 ] );

2. ClassExists

检查一个类或类数组是否存在。示例

// Single class check
$requirements->addCheck( new ClassExists( WP_Error::class ) );

// Multiple classes check
$requirements->addCheck( new ClassExists( [ WP_Error::class, '\Another\Example\Class' ] ) );

3. ExtensionLoaded

检查一个PHP扩展或扩展数组是否已加载。

$check1 = new ExtensionLoaded( 'mbstring' );

$requirements->addCheck( $check1 );

$check2 = new ExtensionLoaded( [ 'mbstring', 'rar' ] );

$requirements->addCheck( $check2 );

4. PHPVersion

检查当前PHP版本是否与给定要求匹配。该检查接受两个参数：要测试的版本和比较运算符。

$check1 = new PHPVersion( '7.2' );

$requirements->addCheck( $check1 );

$check2 = new PHPVersion( '7.2', '<' );

$requirements->addCheck( $check2 );

5. PluginActive

检查插件或插件数组是否在网站上当前激活。

$check1 = new PluginActive( 'contact-form-7/wp-contact-form-7.php' );

$requirements->addCheck( $check1 );

$check2 = new PluginActive( [ 'woocommerce/woocommerce.php', 'elementor/elementor.php' ] );

$requirements->addCheck( $check2 );

6. WPVersion

检查当前WordPress版本是否匹配给定要求。检查接受2个参数：要测试的版本和比较运算符。

$check1 = new WPVersion( '5.7' );

$requirements->addCheck( $check1 );

📖 编写自定义检查

每个检查类必须实现CheckInterface接口并扩展AbstractCheck类。然后您可以提供check方法，该方法负责执行实际检查。

该方法必须返回一个表示检查通过的true布尔值，或者返回一个表示检查失败的WP_Error实例。

以下是一个示例类，该类检查网站是否允许注册。

namespace MyNameSpace\Example;

use Sematico\Diagnostics\Check\AbstractCheck;
use Sematico\Diagnostics\Check\CheckInterface;
use WP_Error;

class RegistrationActive extends AbstractCheck implements CheckInterface {

	/**
	 * Perform the check.
	 *
	 * @return bool|\WP_Error
	 */
	public function check() {

		if ( ! get_option( 'users_can_register' ) ) {
			return new WP_Error( 'my-error', 'My error message here' );
		}

		return true;
	}

}

🚨 安全问题

如果您在WP Diagnostics中发现安全漏洞，请通过电子邮件hello@sematico.com告知。所有安全漏洞都将得到及时处理。

🔖 许可证

在MIT许可证下分发。有关更多信息，请参阅LICENSE文件。