Функция rest_stabilize_value() в WordPress с примером использования

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

rest_stabilize_value( mixed $value )

Параметры

• $value (смешанный): Значение, которое нужно стабилизировать. Это может быть любой тип данных.

Возвращаемое значение

• Возвращает стабилизированное значение в унифицированном виде.

Алгоритм работы функции

1. Если передано скалярное значение или null (проверяется с помощью is_scalar() и is_null()), оно не обрабатывается и возвращается как есть.
2. Если передан объект, он также не обрабатывается и возвращается как есть, но при этом срабатывает функция _doing_it_wrong() с сообщением «Cannot stabilize objects. Convert the object to an array first». Это предупреждает о необходимости преобразования объектов в массивы перед их передачей.
3. Если передан массив, он и все вложенные массивы рекурсивно сортируются по ключам (с использованием ksort()), и новый отсортированный массив возвращается обратно.

Пример 1: Стабилизация строки

$value = 'example string';
$stabilized_value = rest_stabilize_value( $value );
echo $stabilized_value;  // Output: example string

В этом примере строка остается без изменений, так как rest_stabilize_value() просто возвращает строку, если она уже стабилизирована.

Пример 2: Стабилизация массива

Рассмотрим пример с массивом, где ключи расположены в произвольном порядке:

$fruits = [
    'd' => 'avocado',
    'a' => 'orange',
    'b' => 'lemon',
    'c' => 'apple',
];

$stabilized_fruits = rest_stabilize_value( $fruits );
print_r( $stabilized_fruits );

Вернёт:

Array (
    [a] => orange
    [b] => lemon
    [c] => apple
    [d] => avocado
)

Пример 3: Упорядочивание и реструктурирование сложного массива

Допустим, у вас есть массив с вложенными массивами, и вы хотите упорядочить его для лучшего отображения данных:

$list = [
    'fruits' => [
        'lemon' => [
            5 => 'yellow',
            3 => 'sour',
        ],
        'apple' => [
            'yellow',
            'red',
            'green',
        ],
    ],
    'vegetables' => [
        'potato' => [
            'ripe' => true,
            'gmos' => false,
        ],
    ],
];

$stabilized_list = rest_stabilize_value( $list );
print_r( $stabilized_list );

Вернёт:

Array (
    [fruits] => Array (
        [apple] => Array (
            [0] => yellow
            [1] => red
            [2] => green
        )
        [lemon] => Array (
            [3] => sour
            [5] => yellow
        )
    )
    [vegetables] => Array (
        [potato] => Array (
            [gmos] => false
            [ripe] => true
        )
    )
)

В этом примере функция стабилизирует и упорядочивает вложенные массивы по ключам и индексам, чтобы гарантировать их упорядоченность и предсказуемость.

Пример 4: Сравнение двух массивов

$array1 = [
	'one' => 'один',
	'two' => 'два',
	'three' => 'три',
];

$array2 = [
	'two' => 'два',
	'one' => 'один',
	'three' => 'три',
];

var_dump( $array1 === $array2 ); // Вернет false если сравнить исходный формат

var_dump( rest_stabilize_value( $array1 ) === rest_stabilize_value( $array2 ) ); // Вернет true если обработать через функцию

Пример 5: Использование в обработчике REST API запроса

add_action( 'rest_api_init', function () {
    register_rest_route( 'myplugin/v1', '/example', array(
        'methods'  => 'POST',
        'callback' => function( $request ) {
            $data = $request->get_param( 'data' );
            $stabilized_data = rest_stabilize_value( $data );
            return new WP_REST_Response( $stabilized_data, 200 );
        },
    ) );
} );

В этом примере мы используем rest_stabilize_value() для обработки данных, которые приходят через REST API запрос. Функция гарантирует, что данные переданы в стабильном формате перед тем, как они будут возвращены в ответе.

Заключение

Функция rest_stabilize_value() в WordPress предоставляет удобный способ обработки данных, получаемых через REST API. Она помогает стабилизировать значения, обеспечивая их соответствие ожидаемым форматам и предотвращая потенциальные ошибки при обработке данных.