云策 WordPress 开发者社区

类文档

WP_Paused_Extensions_Storage

查看官方原文 ↗
💡 云策文档标注

概述

WP_Paused_Extensions_Storage 是 WordPress 核心类，用于存储和管理暂停的插件或主题的错误信息。它通过选项 API 在恢复模式下记录、检索和删除扩展错误，确保错误处理的安全性和隔离性。

关键要点

  • 类用于存储暂停的插件或主题的错误信息，支持类型为 'plugin' 或 'theme'。
  • 提供方法如 set() 记录错误、get() 获取错误、delete() 删除错误、get_all() 获取所有错误、delete_all() 删除所有错误。
  • 依赖于恢复模式（wp_recovery_mode()）来生成选项名称，确保错误存储的隔离性。
  • 内部使用 is_api_loaded() 检查 API 是否可用，get_option_name() 动态生成选项名。
  • 错误信息基于 error_get_last() 返回的数组结构，包括类型、文件、行号和消息。

代码示例

// 示例：创建存储对象并记录插件错误
$storage = new WP_Paused_Extensions_Storage('plugin');
$error = array(
    'type' => E_ERROR,
    'file' => '/path/to/plugin.php',
    'line' => 42,
    'message' => 'Fatal error occurred'
);
$result = $storage->set('my-plugin', $error); // 返回 true 或 false

// 获取错误
$stored_error = $storage->get('my-plugin'); // 返回错误数组或 null

// 删除错误
$deleted = $storage->delete('my-plugin'); // 返回 true 或 false

注意事项

  • 仅在恢复模式激活时有效，否则 get_option_name() 返回空字符串，导致操作失败。
  • 每个扩展只存储一个错误，后续错误会覆盖之前的记录。
  • 方法返回布尔值或数组/null，需检查返回值以处理成功或失败情况。
  • 选项名称基于会话 ID，格式为 "{session_id}_paused_extensions"，确保多会话隔离。
📄 原文内容

Core class used for storing paused extensions.

Methods

Name Description
WP_Paused_Extensions_Storage::__construct Constructor.
WP_Paused_Extensions_Storage::delete Forgets a previously recorded extension error.
WP_Paused_Extensions_Storage::delete_all Remove all paused extensions.
WP_Paused_Extensions_Storage::get Gets the error for an extension, if paused.
WP_Paused_Extensions_Storage::get_all Gets the paused extensions with their errors.
WP_Paused_Extensions_Storage::get_option_name Get the option name for storing paused extensions.
WP_Paused_Extensions_Storage::is_api_loaded Checks whether the underlying API to store paused extensions is loaded.
WP_Paused_Extensions_Storage::set Records an extension error.

Source

class WP_Paused_Extensions_Storage {

	/**
	 * Type of extension. Used to key extension storage. Either 'plugin' or 'theme'.
	 *
	 * @since 5.2.0
	 * @var string
	 */
	protected $type;

	/**
	 * Constructor.
	 *
	 * @since 5.2.0
	 *
	 * @param string $extension_type Extension type. Either 'plugin' or 'theme'.
	 */
	public function __construct( $extension_type ) {
		$this->type = $extension_type;
	}

	/**
	 * Records an extension error.
	 *
	 * Only one error is stored per extension, with subsequent errors for the same extension overriding the
	 * previously stored error.
	 *
	 * @since 5.2.0
	 *
	 * @param string $extension Plugin or theme directory name.
	 * @param array  $error     {
	 *     Error information returned by `error_get_last()`.
	 *
	 *     @type int    $type    The error type.
	 *     @type string $file    The name of the file in which the error occurred.
	 *     @type int    $line    The line number in which the error occurred.
	 *     @type string $message The error message.
	 * }
	 * @return bool True on success, false on failure.
	 */
	public function set( $extension, $error ) {
		if ( ! $this->is_api_loaded() ) {
			return false;
		}

		$option_name = $this->get_option_name();

		if ( ! $option_name ) {
			return false;
		}

		$paused_extensions = (array) get_option( $option_name, array() );

		// Do not update if the error is already stored.
		if ( isset( $paused_extensions[ $this->type ][ $extension ] ) && $paused_extensions[ $this->type ][ $extension ] === $error ) {
			return true;
		}

		$paused_extensions[ $this->type ][ $extension ] = $error;

		return update_option( $option_name, $paused_extensions, false );
	}

	/**
	 * Forgets a previously recorded extension error.
	 *
	 * @since 5.2.0
	 *
	 * @param string $extension Plugin or theme directory name.
	 * @return bool True on success, false on failure.
	 */
	public function delete( $extension ) {
		if ( ! $this->is_api_loaded() ) {
			return false;
		}

		$option_name = $this->get_option_name();

		if ( ! $option_name ) {
			return false;
		}

		$paused_extensions = (array) get_option( $option_name, array() );

		// Do not delete if no error is stored.
		if ( ! isset( $paused_extensions[ $this->type ][ $extension ] ) ) {
			return true;
		}

		unset( $paused_extensions[ $this->type ][ $extension ] );

		if ( empty( $paused_extensions[ $this->type ] ) ) {
			unset( $paused_extensions[ $this->type ] );
		}

		// Clean up the entire option if we're removing the only error.
		if ( ! $paused_extensions ) {
			return delete_option( $option_name );
		}

		return update_option( $option_name, $paused_extensions, false );
	}

	/**
	 * Gets the error for an extension, if paused.
	 *
	 * @since 5.2.0
	 *
	 * @param string $extension Plugin or theme directory name.
	 * @return array|null Error that is stored, or null if the extension is not paused.
	 */
	public function get( $extension ) {
		if ( ! $this->is_api_loaded() ) {
			return null;
		}

		$paused_extensions = $this->get_all();

		if ( ! isset( $paused_extensions[ $extension ] ) ) {
			return null;
		}

		return $paused_extensions[ $extension ];
	}

	/**
	 * Gets the paused extensions with their errors.
	 *
	 * @since 5.2.0
	 *
	 * @return array {
	 *     Associative array of errors keyed by extension slug.
	 *
	 *     @type array ...$0 Error information returned by `error_get_last()`.
	 * }
	 */
	public function get_all() {
		if ( ! $this->is_api_loaded() ) {
			return array();
		}

		$option_name = $this->get_option_name();

		if ( ! $option_name ) {
			return array();
		}

		$paused_extensions = (array) get_option( $option_name, array() );

		return isset( $paused_extensions[ $this->type ] ) ? $paused_extensions[ $this->type ] : array();
	}

	/**
	 * Remove all paused extensions.
	 *
	 * @since 5.2.0
	 *
	 * @return bool
	 */
	public function delete_all() {
		if ( ! $this->is_api_loaded() ) {
			return false;
		}

		$option_name = $this->get_option_name();

		if ( ! $option_name ) {
			return false;
		}

		$paused_extensions = (array) get_option( $option_name, array() );

		unset( $paused_extensions[ $this->type ] );

		if ( ! $paused_extensions ) {
			return delete_option( $option_name );
		}

		return update_option( $option_name, $paused_extensions, false );
	}

	/**
	 * Checks whether the underlying API to store paused extensions is loaded.
	 *
	 * @since 5.2.0
	 *
	 * @return bool True if the API is loaded, false otherwise.
	 */
	protected function is_api_loaded() {
		return function_exists( 'get_option' );
	}

	/**
	 * Get the option name for storing paused extensions.
	 *
	 * @since 5.2.0
	 *
	 * @return string
	 */
	protected function get_option_name() {
		if ( ! wp_recovery_mode()->is_active() ) {
			return '';
		}

		$session_id = wp_recovery_mode()->get_session_id();
		if ( empty( $session_id ) ) {
			return '';
		}

		return "{$session_id}_paused_extensions";
	}
}

View all references View on Trac View on GitHub

Changelog

Version Description
5.2.0 Introduced.