WP_Error{}
Класс, задача которого упростить обработку ошибок (сообщений) при работе с WordPress (создании плагинов, тем). Этот класс используется при обработке ошибок самим WordPress.
Для того, чтобы начать работу с классом нужно создать его экземпляр, а затем добавлять или удалять в него ошибки (сообщения). Этот класс удобно использовать не только для обработки ошибок, но и для обработки простых сообщений, например: "Настройки сохранены". Чтобы проверить является ли любая переменная PHP экземпляром класса WP_Error в WordPress есть специальная функция is_wp_error().
В параметр $data (данные ошибки) обычно записывается описание ошибки, где можно указать как именно решить проблему. $message и $data это строки и в целом они похожи, но разделаются логикой: $message - сообщение для пользователя и $data - сообщение для разработчика.
Хуки из класса
Возвращает
Ничего не возвращает. Создает объект.
Использование
// прямое использование return new WP_Error( $code, $message, $data ); // добавление нескольких ошибок $errors = new WP_Error; $errors->add( $code, $message, $data ); $errors->add( $code, $message, $data );
- $code(строка/число) (обязательный)
- Код ошибки. Если указать одинаковые коды для разных ошибок, то эти ошибки будут сгруппированы по этому коду. Т.е. затем можно будет получить все ошибки имеющие указанный код.
- $message(строка) (обязательный)
- Сообщение ошибки.
- $data(разное)
Любые дополнительные данные. Получить эти данные можно будет позднее по коду. Смотрите методы
По умолчанию: ''
Примеры
#1 Пример проверки ошибка wp_error
$error = new WP_Error( 'error_key', 'Сообщение ошибки...', 404 ); if( is_wp_error( $error ) ){ echo $error->get_error_code(); //> error_key echo $error->get_error_message(); //> Сообщение ошибки... echo $error->get_error_data(); //> 404 }
Когда функция возвращает созданный в ней экземпляр 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(); // выведет 'Он упал и встать не может' }
В третьем параметре $data можно передать любые данные. Но если ошибка связана с запросом, то в WordPress в этом параметре принято передавать статус код ответа. Например, смотрите код функции wp_handle_comment_submission()
#2 Работа с объектом
Когда мы создаем переменную с экземпляром класса 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>'; } }
#3 Как выглядит экземпляр класса?
Чтобы представлять что собой представляет объект 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 ) ) */ $all_data = $error->get_all_error_data( 'white' ); /* $all_data содержит: Array ( [0] => message ) */ $data = $error->get_error_data( 'white' ); /* $data содержит: message */
Свойства класса
- $errors(массив)
- Ассоциативный массив, содержащий список ошибок. Где ключ - код ошибки, а значение текст ошибки.
- $error_data(массив)
- Ассоциативный массив, содержащий список данных для указанного в $errors кода ошибки.
Заметка: с версии 4.0, эти свойства класса имеют видимость private, но благодаря волшебным методам, их как и прежде можно получить публично.
Методы класса
- public __construct( $code = '', $message = '', $data = '' )
- public add( $code, $message, $data = '' )
- public add_data( $data, $code = '' )
- protected static copy_errors( WP_Error $from, WP_Error $to )
- public export_to( WP_Error $error )
- public get_all_error_data( $code = '' )
- public get_error_code()
- public get_error_codes()
- public get_error_data( $code = '' )
- public get_error_message( $code = '' )
- public get_error_messages( $code = '' )
- public has_errors()
- public merge_from( WP_Error $error )
- public remove( $code )
- __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 )(WP 4.1)
- Удаляет ошибку (сообщение) из объекта по переданному ключу (коду). Ничего не возвращает.
- has_errors()(WP 5.1)
- Возвращает логическое значение, указывающее, содержит ли экземпляр ошибки.
Список изменений
С версии 2.1.0 | Введена. |