Функция wp_send_json_error() в WordPress: Описание и Примеры Использования

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

wp_send_json_error() автоматически устанавливает заголовок Content-Type как application/json. Важно указать соответствующий HTTP статус код, если необходимо явно показать ошибку, например, 500, иначе будет возвращен статус 200 (успех).

Если в качестве параметра $data передать объект WP_Error, он будет обработан и преобразован в массив с кодами и сообщениями об ошибках.

wp_send_json_error( mixed $data = null, int $status_code = null, int $options = 0 )

Параметры

• $data (смешанный) – Необязательный. Данные для включения в ответ JSON, которые будут размещены в ключе data. Может быть строкой, массивом, объектом, числом и т.д.
  По умолчанию: null
• $status_code (целое число) – Необязательный. HTTP-статус ответа. Рекомендуется использовать коды, соответствующие ошибкам (например, 400 или 500).
  По умолчанию: null
• $options (целое число) – Необязательный. Опции для json_encode(), такие как JSON_PRETTY_PRINT и JSON_UNESCAPED_UNICODE.
  По умолчанию: 0

Пример 1: Простое сообщение об ошибке в ответе AJAX

Пример JavaScript-кода, который отправляет AJAX-запрос и обрабатывает ответ с ошибкой:

jQuery(document).ready(function($) {
    $('#submit_button').on('click', function(e) {
        e.preventDefault();

        $.post(
            ajaxurl,
            { action: 'handle_ajax_request', field_value: $('#input_field').val() },
            function(response) {
                if (response.success) {
                    alert("Данные успешно отправлены: " + response.data.message);
                } else {
                    alert("Ошибка: " + response.data);
                }
            }
        );
    });
});

PHP-код, обрабатывающий AJAX-запрос и возвращающий ошибку с использованием wp_send_json_error():

add_action('wp_ajax_handle_ajax_request', 'handle_ajax_request_callback');

function handle_ajax_request_callback() {
    if (empty($_POST['field_value'])) {
        wp_send_json_error('Значение поля не должно быть пустым', 400);
    }
    
    // Обработка данных...
    wp_send_json_success(['message' => 'Данные успешно обработаны!']);
}

Результат: При пустом значении поля, клиентская сторона получит JSON с success: false и сообщением Значение поля не должно быть пустым.

Пример 2: Передача объекта WP_Error для отображения детализированной ошибки

При передаче объекта WP_Error в wp_send_json_error() он будет преобразован в массив с кодами и сообщениями об ошибках.

function handle_ajax_with_wp_error() {
    if (!is_user_logged_in()) {
        $error = new WP_Error('not_logged_in', 'Требуется авторизация для выполнения этого действия.');
        wp_send_json_error($error, 403);
    }
    
    // Остальная часть логики...
}

На клиенте JSON-ответ будет выглядеть так:

{
  "success": false,
  "data": [
    { "code": "not_logged_in", "message": "Требуется авторизация для выполнения этого действия." }
  ]
}

Теперь, чтобы отобразить сообщение об ошибке, можно использовать response.data[0].message.

Пример 3: Использование опций JSON и пользовательского кода статуса

Функция wp_send_json_error() позволяет установить код статуса и задать опции для json_encode(), например, для улучшения читаемости JSON-ответа.

function custom_error_with_status() {
    if (!isset($_POST['security']) || !wp_verify_nonce($_POST['security'], 'my_nonce_action')) {
        wp_send_json_error('Ошибка проверки безопасности', 403, JSON_PRETTY_PRINT);
    }
    
    // Дополнительная логика...
}

Результат: Ответ будет иметь статус 403 Forbidden и отформатированный JSON, что полезно при отладке.

Пример 4: Обработка специфичной ошибки на стороне клиента

Если требуется передать специфичный код ошибки, можно использовать его для создания более детализированной логики на стороне клиента.

function ajax_custom_error_codes() {
    $data = [
        'error_code' => 'invalid_request',
        'message' => 'Запрос не соответствует требуемому формату.'
    ];

    wp_send_json_error($data, 400);
}

На стороне клиента можно добавить проверку для error_code:

$.post(ajaxurl, { action: 'ajax_custom_error_codes' }, function(response) {
    if (!response.success) {
        if (response.data.error_code === 'invalid_request') {
            alert("Некорректный запрос: " + response.data.message);
        } else {
            alert("Ошибка: " + response.data.message);
        }
    }
});

Заключение

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