wp_send_json_error() │ WP 3.5.0

Функция wp_send_json_error() используется для отправки ответа в формате JSON на AJAX-запрос, указывая на ошибку. Это значит, что когда какой-то запрос не удался, с помощью данной функции мы можем вернуть информацию об ошибке.

Как это работает

Когда вы вызываете wp_send_json_error(), функция отправляет заголовок, ко��орый говорит, что мы отправляем JSON-данные:

@header( 'Content-Type: application/json; charset=' . get_option( 'blog_charset' ) );

Этот заголовок указывает, что данные передаются в формате JSON. Функция завершает выполнение скрипта с помощью команды die().

Просто вызвав wp_send_json_error(), вы не укажете ответ об ошибке — функция вернёт статус 200 (успех). Для того чтобы явно указать, что AJAX-запрос завершился с ошибкой, необходимо передать код ошибки через параметр $status_code, например, 500.

С версии 4.1, если вы передаёте объект WP_Error в параметре $data, функция обработает его и вернет массив с сообщением об ошибке. Это значит, функция понимает переданный объект WP_Error.

Для успешного ответа используется функция wp_send_json_success() — она делает противоположное и отправляет сообщение об успехе.

Возвращаемые данные

Функция возвращает null, показывает данные на экране и завершает выполнение PHP-скрипта.

Тип данных, возвращаемый перед кодированием в JSON:

array( 'success' => false );

Если указан параметр $data:

array( 'success' => false, 'data' => $data );

Использование

wp_send_json_error( $value, $status_code, $flags );

Параметры:

• $value (mixed) — Данные, которые нужно закодировать в JSON и вывести. По умолчанию: null

• $status_code (int) — HTTP код статус, который будет выведен. Что такое статус-коды, вы можете найти более подробно в документации.

• $options (int) — Опции, которые передаются в json_encode(). Возможные значения:

  • JSON_FORCE_OBJECT
  • JSON_HEX_QUOT
  • JSON_HEX_TAG
  • JSON_HEX_AMP
  • JSON_HEX_APOS
  • JSON_INVALID_UTF8_IGNORE
  • JSON_INVALID_UTF8_SUBSTITUTE
  • JSON_NUMERIC_CHECK
  • JSON_PARTIAL_OUTPUT_ON_ERROR
  • JSON_PRESERVE_ZERO_FRACTION
  • JSON_PRETTY_PRINT
  • JSON_UNESCAPED_LINE_TERMINATORS
  • JSON_UNESCAPED_SLASHES
  • JSON_UNESCAPED_UNICODE
  • JSON_THROW_ON_ERROR

Смысл этих констант описан на странице с константами JSON.

Примеры использования

Пример 1: Передача WP_Error в $data

Вы можете передать объект WP_Error в параметре $data:

$error = new WP_Error( 'error_code', 'ОШИБКА: Неверные учетные данные.' );

wp_send_json_error( $error );

Теперь, когда вы получаете данные в JavaScript, ответ будет содержать массив со всеми ошибками в следующем виде (обычно только один элемент):

{
  "success": false,
  "data": [
    {
      "code": "error_code",
      "message": "ОШИБКА: Неверные учетные данные."
    }
  ]
}

Вы можете получить сообщение об ошибке так:

response.data[0].message

Пример 2: Возврат ошибки в формате JSON на AJAX-запрос

Этот код на jQuery отправляет AJAX-запро�� на страницу плагина ajax/save_field.php:

fetch( ${ pluginUrl }/ajax/save_field.php )
  .then( resp => resp.json() )
  .then( res => {
    if( res.success ){
      alert( res.data )
    } else {
      alert( res.data )
    }
  })

А вот код файла /ajax/save_field.php, который обрабатывает полученный запрос. Он показывает, как вернуть ошибки:

function wp_send_json_error( $value = null, $status_code = null, $flags = 0 ) {
  $response = array( 'success' => false );

  if ( isset( $value ) ) {
    if ( is_wp_error( $value ) ) {
      $result = array();
      foreach ( $value->errors as $code => $messages ) {
        foreach ( $messages as $message ) {
          $result[] = array(
            'code'    => $code,
            'message' => $message,
          );
        }
      }
      $response['data'] = $result;
    } else {
      $response['data'] = $value;
    }
  }

  wp_send_json( $response, $status_code, $flags );
}