README

此插件需要 PHP 7.2+，但强烈建议用户使用非 EOL（已停止支持）的 PHP 版本。有关仍受支持的 PHP 版本的最新列表，请参阅：https://php.ac.cn/supported-versions.php。

• 此插件的 0.1.* 版本将是最后一个支持 PHP 7.2 的版本。

安装

1. 克隆 git 仓库 git clone git@bitbucket.org:studiocreativateam/pab-wp.git 或通过 composer 安装 composer require studiocreativateam/pab-wp。
2. 如果您克隆了仓库，则需要转到 pab-wp 项目的文件夹并运行 composer install 命令以获取依赖项。
3. 现在您可以将文件夹压缩成 .zip 文件并上传到 WordPress 插件。
4. 按照以下说明配置您的密钥
5. 通过 WordPress 管理界面激活插件

注意：此插件默认不执行任何操作，并且没有管理界面。首先必须配置密钥。

配置

（可选）通过将以下代码片段添加到您的 wp-config.php 中来跟踪 PHP 错误，并将 PAB_TOKEN 替换为您的实际项目令牌

define( 'WP_PAB_TOKEN', 'PAB_TOKEN' );

将此代码片段添加到您的 wp-config.php 中，并将 PAB_PRIVATE_KEY 替换为您的实际私钥

define( 'WP_PAB_PRIVATE_KEY', 'PAB_PRIVATE_KEY' );

注意：不要设置常量以禁用 PHP 跟踪器。

（可选）设置 PHP 跟踪器将跟踪的错误类型

define( 'WP_PAB_ERROR_TYPES', E_ALL & ~E_DEPRECATED & ~E_NOTICE & ~E_USER_DEPRECATED );

（可选）如果此标志启用，则某些个人身份信息将由活动集成添加。如果没有此标志，它们从一开始就不会添加到事件中。

如果可能，建议启用此功能并使用服务器端 PII 去除来删除值。

启用时，当前登录用户和 IP 地址将被添加到事件中。

define( 'WP_PAB_SEND_DEFAULT_PII', true );

（可选）定义您站点的版本；默认情况下将使用主题版本。这用于跟踪错误发生在您站点的哪个版本。当与版本跟踪结合使用时，这是一个非常强大的功能。

define( 'WP_PAB_VERSION', 'v0.1.1' );

（可选）定义您站点的环境。默认为 未指定。

define( 'WP_PAB_ENV', 'production' );

过滤器

此插件为插件/主题开发者提供了以下过滤器。

请注意，某些过滤器在 PAB 跟踪器初始化时触发，因此如果您在主题或加载在 WP PAB 之后的插件中定义它们，则它们不会触发。

适用于所有跟踪器

wp_pab_user_context (数组)

您可以使用此过滤器扩展 PHP 和 JS 跟踪器的 PAB 用户上下文。

警告：这些值在 JS 跟踪器中暴露给公众，因此请确保您不会暴露任何私密信息！

示例用法

add_filter( 'wp_pab_user_context', function ( array $user ) {
	return array_merge( $user, array(
		'a-custom-user-meta-key' => 'custom value',
	));
} );

注意：此过滤器在 WordPress set_current_user 动作上触发，并且只有当 WP_PAB_SEND_DEFAULT_PII 常量设置为 true 时才会触发。

特定于 PHP 跟踪器

wp_pab_token (字符串)

您可以使用此过滤器覆盖 PHP 跟踪器使用的 PAB 令牌。

警告：不建议这样做，请使用 wp-config.php 中的 WP_PAB_TOKEN 常量设置令牌！

示例用法

add_filter( 'wp_pab_token', function ( $token ) {
	return 'xxxxxxxxxxxxxxxxxxxxxx';
} );

注意：此过滤器在 WordPress after_setup_theme 动作上触发。不鼓励使用此功能，而是建议使用 WP_PAB_TOKEN 常量在 wp-config.php 中定义令牌。

wp_pab_scope (void)

您可以使用此过滤器自定义 PAB。

示例用法

add_filter( 'wp_pab_scope', function ( \PAB\State\Scope $scope ) {
	$scope->setTag('my-custom-tag', 'tag-value');

	return $scope;
} );

注意：此过滤器在 WordPress after_setup_theme 动作上触发。

wp_pab_options

您可以使用此过滤器自定义 PAB。

示例用法

add_filter( 'wp_pab_options', function ( \PAB\Options $options ) {
	// Only sample 90% of the events
	$options->setSampleRate(0.9);

	return $options;
} );

注意： 黑名单和白名单选项数组中带有 regex: 前缀的项将被转换为纯正则表达式。

高级用法

大量通知

WordPress生态系统中的许多插件都会生成通知，这些通知会被PAB插件捕获。

这可能导致事件数量激增，甚至因为将这些事件传输到PAB而导致页面加载速度变慢。

为了防止这种情况，你可以在你的 wp-config.php 中设置以下内容以过滤掉通知类型的错误。

define( 'WP_PAB_ERROR_TYPES', E_ALL & ~E_NOTICE );

捕获已处理的异常

处理异常的最佳做法是自己捕获它，然而你可能仍然想了解它。

PAB插件只捕获未处理的异常和致命错误，要捕获已处理的异常，你可以执行以下操作

try {
	myMethodThatCanThrowAnException();
} catch ( \Exception $e ) {
	// We are using wp_pab_safe to make sure this code runs even if the PAB plugin is disabled
	if ( function_exists( 'wp_pab_safe' ) ) {
		wp_pab_safe( function ( \PAB\State\HubInterface $client ) use ( $e ) {
			$client->captureException( $e );
		} );
	}

	wp_die( 'There was an error doing this thing you were doing, we have been notified!' );
}

如果你只为已处理的异常附加额外的数据，可以添加

$e = new Exception('Some exception I want to capture with extra data.');

if (function_exists('wp_pab_safe')) {
	wp_pab_safe(function (\PAB\State\HubInterface $client) use ($e) {
		$client->withScope(function (\PAB\State\Scope $scope) use ($client, $e) {
			$scope->setExtra('user_data', $e->getData());
			$client->captureException($e);
		});
	});
}

如果你需要在所有情况下都添加数据到作用域，请使用 configureScope 在 wp_pab_scope 过滤器 中。

在WordPress之前加载PAB

由于WP PAB是一个WordPress插件，它会在WordPress之后加载，除非你使用必须使用的插件，否则在加载一些其他插件后可能会抛出PAB无法捕获的错误。

为了解决这个问题，你可以选择在WordPress启动之前通过你的 wp-config.php 文件加载插件。

通过将以下代码片段添加到你的 wp-config.php 中（在 /* That's all, stop editing! Happy blogging. */ 注释之前），可以轻松实现这一点

require_once ABSPATH . 'wp-content/plugins/pab-wp/pab-wp.php';

此外，请确保在上述代码片段之前设置了任何配置选项，如 WP_PAB_TOKEN，否则它们将没有任何效果。

捕获插件错误

由于此插件名为 pab-wp，它加载较晚，可能会错过在它之前加载的插件中发生的错误或通知。

你可以通过将WordPress PAB作为必须使用的插件加载来解决这个问题，通过创建文件 wp-content/my-plugins/pab-wp.php（如果 my-plugins 目录不存在，则必须创建该目录）。

<?php

/**
 * Plugin Name: WordPress PAB
 * Plugin URI: https://studio-creativa.pl
 * Description: A (unofficial) WordPress plugin to report PHP errors to PAB.
 * Version: must-use-proxy
 * Author: Jacek Labudda
 * Author URI: https://studio-creativa.pl
 * License: MIT
 */

$wp_pab = ABSPATH . 'plugins/pab-wp/pab-wp.php';

// Do not crash in case the plugin is not installed
if ( ! file_exists( $wp_pab ) ) {
	return;
}

require $wp_pab;

现在 pab-wp 将始终加载，并在所有其他插件之前。

注意：我们建议你保留原始的 pab-wp 在 /wp-content/plugins 文件夹中，以便通过WordPress更新器接收更新。但是，如果上述脚本处于活动状态（因为它将始终处于启用状态），则启用或禁用没有任何作用。

仅从某些主题和/或插件捕获错误

这是一个示例，说明如何使用PAB SDK的 before_send 回调仅捕获在特定主题或插件中发生的错误。

add_filter( 'wp_pab_options', function ( \PAB\Options $options ) {
	$options->setBeforeSendCallback( function ( \PAB\Event $event ) {
		$exceptions = $event->getExceptions();

		// No exceptions in the event? Send the event to PAB, it's most likely a log message
		if ( empty( $exceptions ) ) {
			return $event;
		}

		$stacktrace = $exceptions[0]->getStacktrace();

		// No stacktrace in the first exception? Send it to PAB just to be safe then
		if ( $stacktrace === null ) {
			return $event;
		}

		// Little helper and fallback for PHP versions without the str_contains function
		$strContainsHelper = function ( $haystack, $needle ) {
			if ( function_exists( 'str_contains' ) ) {
				return str_contains( $haystack, $needle );
			}

			return $needle !== '' && mb_strpos( $haystack, $needle ) !== false;
		};

		foreach ( $stacktrace->getFrames() as $frame ) {
			// Check the the frame happened inside our theme or plugin
			// Change THEME_NAME and PLUGIN_NAME to whatever is required
			// And / or modify this `if` statement to detect other variables
			if ( $strContainsHelper( $frame->getFile(), 'themes/THEME_NAME' )
				 || $strContainsHelper( $frame->getFile(), 'plugins/PLUGIN_NAME' )
			) {
				// Send the event to PAB
				return $event;
			}
		}

		// Stacktrace contained no frames in our theme and/or plugin? We send nothing to PAB
		return null;
	} );

	return $options;
} );

在初始化之前修改PHP SDK ClientBuilder 或选项

由于PHP SDK初始化得很快以捕获早期错误，因此无法使用WordPress钩子修改选项或 ClientBuilder。

通过使用名为 WP_PAB_CLIENTBUILDER_CALLBACK 的常量设置回调，可以在初始化之前修改选项和 ClientBuilder。

当插件创建新的 ClientBuilder 实例以创建新的PHP SDK客户端时，将执行回调。

你可以在 wp-config.php 文件中放置以下示例，以确保在PHP SDK初始化之前它可用

function wp_pab_clientbuilder_callback( \PAB\ClientBuilder $builder ): void {
    // For example, disabling the default integrations 
	$builder->getOptions()->setDefaultIntegrations( false );
}

define( 'WP_PAB_CLIENTBUILDER_CALLBACK', 'wp_pab_clientbuilder_callback' );

安全漏洞

如果你在WordPress PAB（pab-wp）中发现安全漏洞，请将电子邮件发送到Jacek Labudda（j.labudda@studio-creativa.pl）。所有安全漏洞都将迅速解决。

许可协议

WordPress PAB（pab-wp）插件是开源软件，根据 MIT许可协议 授权。