WordPress как на ладони
wordpress jino

WP_Error{} WP 2.1

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

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

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

Хуков нет.

Возвращает

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

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

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

Первый подход
$error = new WP_Error( 'error_key', 'Сообщение ошибки...' );

if( is_wp_error( $error ) ){
	echo $error->get_error_code();    //> error_key
	echo $error->get_error_message(); //> Сообщение ошибки...    
}

Когда функция возвращает созданный в ней экземпляр 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. Приведу пример создания экземпляра и добавления в него ошибок, и их обработку:

// Создаем экземпляр
global $form_error;
$form_error = new WP_Error;

// любая функция, может быть в другом файле
function foo(){
	global $form_error;

	// какой-то код ..

	// проверка поля
	if( empty( $email ) ){
		$form_error->add('no_email', 'Заполните email');
	}
	elseif( ! is_email( $email ) ){
		$form_error->add('invalid_email', 'Некорректный email');
	}

	// Проверяем есть ли ошибка обрываем работу функции
	if ( $form_error->get_error_code() )
		return; // выходим дальше работу функции не продолжаем из за ошибки

}

// Другой файл (не тот где функция foo() или тот, не важно) - файл где выводятся 
// сообщения об ошибках если такие имеются.
// Проверяем есть ли ошибка и выводим все сообщения, если ошибка
if ( $form_error->get_error_code() ) {
	foreach( $form_error->get_error_messages() as $error ){
		echo '<div><strong>Ошибка</strong>:'. $error .'</div>';
	}
}

Как выглядит экземпляр класса?

Чтобы представлять что собой представляет объект WP_Error, предлагаю посмотреть на него в заполненном виде:

// создаем экземпляр и сразу добавляем данные - метод add()
$error = new WP_Error('fallen', 'Жук упал и встать не может.');

// добавим еще данные в объект
$error->add('help', 'Ждет он, кто ему поможет.');

/* $error содержит
WP_Error Object
(
	[errors] => Array
		(
			[fallen] => Array
				(
					[0] => Жук упал и встать не может.
				)

			[help] => Array
				(
					[0] => Ждет он, кто ему поможет.
				)

		)

	[error_data] => Array
		(
		)

)
*/

// Добавим еще данные и укажем третий параметр
$error->add('frost', 'Иней лег на ветви ели.', 'error');
$error->add('white', 'Иглы за ночь побелели.', 'message');

/* теперь $error содержит
WP_Error Object
(
	[errors] => Array
		(
			[fallen] => Array
				(
					[0] => Жук упал и встать не может.
				)

			[help] => Array
				(
					[0] => Ждет он, кто ему поможет.
				)

			[frost] => Array
				(
					[0] => Иней лег на ветви ели.
				)

			[white] => Array
				(
					[0] => Иглы за ночь побелели.
				)

		)

	[error_data] => Array
		(
			[frost] => error
			[white] => message
		)

)
*/

Свойства класса

$errors(массив)
Ассоциативный массив, содержащий список ошибок. Где ключ - код ошибки, а значение текст ошибки.
$error_data(массив)
Ассоциативный массив, содержащий список данных для указанного в $errors кода ошибки.

Заметка: с версии 4.0, эти свойства класса имеют видимость private, но благодаря волшебным методам, их как и прежде можно получить публично.

Методы класса

__construct( $code = '', $message = '', $data = '' )
Добавляет ошибку в объект (код (ключ), текст, дополнительные данные). Если параметр $code не установлен, то остальные параметры будут проигнорированы. Если $code установлен, то параметр $message будет использован даже если там пустая строка, но параметр $data в этом случае, будет использован только если он не пустой.С помощью метода add() можно создавать несколько сообщений под одним кодом.
get_error_codes()
Получает все ключи ошибок. Доступ публичный, возвращает массив кодов ошибок, если таковые имеются.
get_error_code()
Получает первый ключ ошибки. Доступ публичный, возвращает строку/число или пустую строку, если кодов вообще нет.
get_error_messages( $code = '' )
Получает все тексты ошибок или все тексты ошибок под указанным ключом. Доступ публичный, возвращает массив текстов ошибок или пустой массив, если ошибок нет.
get_error_message( $code = '' )
Получает отдельное сообщение (текст) по переданному коду (ключу) ошибки. Если под ключом несколько сообщений, то вернется только первое. Если параметр $code не передан, то будет обработан первый ключ.
get_error_data( $code = '' )
Получает данные ошибки по переданному ключу (коду) ошибки. Вернет значение (строку/массив/булев) или null если данных нет.
add( $code, $message, $data = '' )
Добавляет сообщения в объект (в список ошибок). Ничего не возвращает.
add_data( $data, $code = '' )
Добавляет данные ошибки (текста) связанные с указанным ключом (кодом) ошибки (текста).
remove( $code )
Удаляет ошибку (сообщение) из объекта по переданному ключу (коду). Ничего не возвращает. С версии 4.1.

Код WP Error: wp-includes/class-wp-error.php WP 4.8.2

<?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 ] );
	}
}

Cвязанные функции

Из метки: wp_error

Еще из раздела: Классы

WP_Error Комментариев нет

Здравствуйте, !

Ваш комментарий