WP_Error

Класс задача которого упростить обработку ошибок (сообщений) при работе с WordPress (создании плагинов, тем). Этот класс используется при обработке ошибок самим WordPress.

Для того, чтобы начать работу с классом нужно создать его экземпляр, а затем добавлять или удалять в него ошибки (сообщения). Этот класс удобно использовать не только для обработки ошибок, но и для обработки простых сообщений, например: “Настройки сохранены”. Чтобы проверить является ли любая переменная PHP экземпляром класса WP_Error в WordPress есть специальная функция is_wp_error().

В параметр $data (данные ошибки) обычно записывается описание ошибки, где можно указать как именно решить проблему. $message и $data это строки и в целом они похожи, но разделаются логикой: $message – сообщение для пользователя и $data – сообщение для разработчика.

Хуков нет.

Возвращает

Ничего не возвращает. Создает объект.

Как работать с классом?

Я вижу два подхода работы с классом.

Первый подход

Когда функция возвращает созданный в ней экземпляр WP_Error, который затем проверяется функцией is_wp_error(). По такому принципу, например, работает функция WordPress wp_insert_post() – в случае ошибки, она возвращает объект WP_Error, в котором содержится информация об ошибке(ах). Коротко такой подход можно записать так:

function some_stuff( $some = false ){
	// Переменная $some должна быть указана
	if( ! $some )
		return new WP_Error('fallen', 'Он упал и встать не может');
	else
		return true;
}

// теперь вызываем функцию, чтобы она вернула ошибку
$return = some_stuff();

// проверяем переменную на наличие ошибки
if( is_wp_error( $return ) ){
	// выводим сообщение ошибки
	echo $return->get_error_message(); // выведет 'Он упал и встать не может'
}
Второй подход

Когда мы создаем переменную с экземпляром класса WP_Error и затем работаем с этой переменной, можно в другом классе или в другой функции, группе функций, где угодно.

Например, мы делаем форму обратной связи и нам нужно обрабатывать ошибки, в этом случает хорошо подойдет экземпляр класса WP_Error. Приведу пример создания экземпляра и добавления в него ошибок, и их обработку:

<?php
class WP_Error {
	/**
	 * Stores the list of errors.
	 *
	 * @since 2.1.0
	 * @var array
	 */
	public $errors = array();

	/**
	 * Stores the list of data for error codes.
	 *
	 * @since 2.1.0
	 * @var array
	 */
	public $error_data = array();

	/**
	 * Initialize the error.
	 *
	 * If `$code` is empty, the other parameters will be ignored.
	 * When `$code` is not empty, `$message` will be used even if
	 * it is empty. The `$data` parameter will be used only if it
	 * is not empty.
	 *
	 * Though the class is constructed with a single error code and
	 * message, multiple codes can be added using the `add()` method.
	 *
	 * @since 2.1.0
	 *
	 * @param string|int $code Error code
	 * @param string $message Error message
	 * @param mixed $data Optional. Error data.
	 */
	public function __construct( $code = '', $message = '', $data = '' ) {
		if ( empty($code) )
			return;

		$this->errors[$code][] = $message;

		if ( ! empty($data) )
			$this->error_data[$code] = $data;
	}

	/**
	 * Retrieve all error codes.
	 *
	 * @since 2.1.0
	 * @access public
	 *
	 * @return array List of error codes, if available.
	 */
	public function get_error_codes() {
		if ( empty($this->errors) )
			return array();

		return array_keys($this->errors);
	}

	/**
	 * Retrieve first error code available.
	 *
	 * @since 2.1.0
	 * @access public
	 *
	 * @return string|int Empty string, if no error codes.
	 */
	public function get_error_code() {
		$codes = $this->get_error_codes();

		if ( empty($codes) )
			return '';

		return $codes[0];
	}

	/**
	 * Retrieve all error messages or error messages matching code.
	 *
	 * @since 2.1.0
	 *
	 * @param string|int $code Optional. Retrieve messages matching code, if exists.
	 * @return array Error strings on success, or empty array on failure (if using code parameter).
	 */
	public function get_error_messages($code = '') {
		// Return all messages if no code specified.
		if ( empty($code) ) {
			$all_messages = array();
			foreach ( (array) $this->errors as $code => $messages )
				$all_messages = array_merge($all_messages, $messages);

			return $all_messages;
		}

		if ( isset($this->errors[$code]) )
			return $this->errors[$code];
		else
			return array();
	}

	/**
	 * Get single error message.
	 *
	 * This will get the first message available for the code. If no code is
	 * given then the first code available will be used.
	 *
	 * @since 2.1.0
	 *
	 * @param string|int $code Optional. Error code to retrieve message.
	 * @return string
	 */
	public function get_error_message($code = '') {
		if ( empty($code) )
			$code = $this->get_error_code();
		$messages = $this->get_error_messages($code);
		if ( empty($messages) )
			return '';
		return $messages[0];
	}

	/**
	 * Retrieve error data for error code.
	 *
	 * @since 2.1.0
	 *
	 * @param string|int $code Optional. Error code.
	 * @return mixed Error data, if it exists.
	 */
	public function get_error_data($code = '') {
		if ( empty($code) )
			$code = $this->get_error_code();

		if ( isset($this->error_data[$code]) )
			return $this->error_data[$code];
	}

	/**
	 * Add an error or append additional message to an existing error.
	 *
	 * @since 2.1.0
	 * @access public
	 *
	 * @param string|int $code Error code.
	 * @param string $message Error message.
	 * @param mixed $data Optional. Error data.
	 */
	public function add($code, $message, $data = '') {
		$this->errors[$code][] = $message;
		if ( ! empty($data) )
			$this->error_data[$code] = $data;
	}

	/**
	 * Add data for error code.
	 *
	 * The error code can only contain one error data.
	 *
	 * @since 2.1.0
	 *
	 * @param mixed $data Error data.
	 * @param string|int $code Error code.
	 */
	public function add_data($data, $code = '') {
		if ( empty($code) )
			$code = $this->get_error_code();

		$this->error_data[$code] = $data;
	}

	/**
	 * Removes the specified error.
	 *
	 * This function removes all error messages associated with the specified
	 * error code, along with any error data for that code.
	 *
	 * @since 4.1.0
	 *
	 * @param string|int $code Error code.
	 */
	public function remove( $code ) {
		unset( $this->errors[ $code ] );
		unset( $this->error_data[ $code ] );
	}
}