Функция wp_send_json() в WordPress: синтаксис, применение и примеры использования

## Функция WP_SEND_JSON()

Функция wp_send_json() предназначена для преобразования переданной переменной в формат JSON, вывода результата на экран и завершения выполнения скрипта. Она используется для возврата данных по AJAX-запросам.

### HTTP Заголовок

При выполнении этой функции устанавливается следующий HTTP заголовок:

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

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

Эта функция используется в следующих контекстах:

- wp_send_json_success()
- wp_send_json_error()

Обратите внимание, что в ней нет хуков.

### Возврат Значений

Функция не возвращает никаких значений (null). Она просто завершает выполнение скрипта.

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

Функция имеет следующий синтаксис:

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

- **$response** (string/array/number/object/bool, обязательный) — переменная, обычно это массив или объект, который будет закодирован в формат JSON.
- **$status_code** (number) (добавлен в WP 4.7) — код статуса HTTP. Список кодов статусов можно найти в документации.
- **$flags** (number) (добавлен в WP 5.6) — параметры, передаваемые функции 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.

  По умолчанию: 0.

### Пример AJAX Запроса

Вот пример, как отправить AJAX-запрос и получить результат в формате JSON. Этот код отправляет запрос на страницу плагина ajax/save_field.php.

```javascript
jQuery(document).ready(function() {
    jQuery('#btn_save').click(function(e) {
        e.preventDefault();

        jQuery.post(
            pluginUrl + 'ajax/save_field.php',
            jQuery('#my-form').serialize(),
            function(data) {
                alert(data.message + " ID:" + data.ID);
                // Это выведет сообщение "Saved ID:1"
            }
        );
    });
});

Код Обработчика Запроса

Вот код файла, который принимает запрос. Он использует wp_send_json(), чтобы удобно вернуть результат в формате JSON:

 'Saved',
    'ID' => 1
);

wp_send_json($return);

// Функция сама завершает выполнение скрипта,
// поэтому нет необходимости использовать die или exit

Изменения

• С версии 3.5.0 — функция была введена.
• С версии 4.7.0 — был добавлен параметр $status_code.
• С версии 5.6.0 — был добавлен параметр $flags.

Код Функции

Вот код функции wp_send_json() из файла wp-includes/functions.php:

function wp_send_json($response, $status_code = null, $flags = 0) {
    if (wp_is_serving_rest_request()) {
        _doing_it_wrong(
            __FUNCTION__,
            sprintf(
                /* translators: 1: WP_REST_Response, 2: WP_Error */
                __('Возвращайте объект %1$s или %2$s из вашего колбэка при использовании REST API.'),
                'WP_REST_Response',
                'WP_Error'
            ),
            '5.5.0'
        );
    }

    if (!headers_sent()) {
        header('Content-Type: application/json; charset=' . get_option('blog_charset'));
        if (null !== $status_code) {
            status_header($status_code);
        }
    }

    echo wp_json_encode($response, $flags);

    if (wp_doing_ajax()) {
        wp_die(
            '',
            '',
            array(
                'response' => null,
            )
        );
    } else {
        die;
    }
}