Функция build_query() предназначена для создания строки параметров URL на основе массива данных. Она является оберткой для функции _http_build_query() и используется для генерации URL-строк запроса. В отличие от стандартной PHP-функции http_build_query(), build_query() не выполняет URL-кодирование символов, предоставляя упрощенный подход для создания URL-параметров.
build_query( array $data ): stringbuild_query() принимает массив данных и генерирует строку запроса, разделяя пары ключ/значение символом &. Это удобно, если необходимо быстро добавить параметры запроса к URL. Функция часто применяется для сборки строк запроса в REST-запросах и API-вызовах, где параметры должны быть переданы без дополнительного кодирования.
Возвращаемое значение
- string: возвращает строку, представляющую параметры URL-запроса.
Пример 1: Основное использование функции build_query()
В этом примере массив данных преобразуется в строку запроса:
$data = [ 'item' => 'apple', 'quantity' => 5 ];
echo build_query( $data );
// Результат: item=apple&quantity=5
Здесь параметры item и quantity превращаются в строку URL-запроса, которая может быть добавлена к основному URL.
Пример 2: Сравнение с http_build_query()
Функция http_build_query() выполняет дополнительное URL-кодирование, поэтому результат будет отличаться:
$data = [ 'key/special' => 'value with spaces' ];
echo build_query( $data );
// Результат: key/special=value with spaces
echo http_build_query( $data );
// Результат: key%2Fspecial=value+with+spaces
В этом случае build_query() сохраняет пробелы, а http_build_query() кодирует их как +, что может потребоваться для более строгих URL-правил.
Пример 3: Создание строки запроса для API-запроса
Этот пример показывает, как можно создать строку запроса для API-запроса, используя параметры для фильтрации данных:
$params = [
'action' => 'get_data',
'format' => 'json'
];
$query = build_query($params);
$response = wp_remote_get("https://api.example.com/data?$query");
if ( ! is_wp_error( $response ) && wp_remote_retrieve_response_code( $response ) === 200 ) {
$data = json_decode( wp_remote_retrieve_body( $response ), true );
print_r( $data );
}
Здесь build_query() формирует строку запроса на основе параметров, которые затем добавляются к URL для выполнения запроса к API.
Пример 4: Использование с null и логическими значениями
Функция build_query() также корректно работает с null, true, и false значениями, обрабатывая их по логике WordPress:
$params = [ 'one' => null, 'two' => true, 'three' => false ];
echo build_query($params);
// Результат: two=1&three=0
Значение null исключается из строки запроса, true преобразуется в 1, а false — в 0.
Связанные функции
WordPress предлагает несколько функций для создания и обработки строк запросов:
add_query_arg()— позволяет добавлять параметры в существующий URL.http_build_query()— стандартная PHP-функция для построения URL-кодированных строк (с кодированием символов).wp_parse_str()— разбирает строку запроса и возвращает массив.
Заключение
Функция build_query() упрощает создание строк параметров URL в WordPress, делая код удобочитаемым и компактным. Она является предпочтительным выбором для быстрого формирования строк запросов без дополнительного кодирования символов. Используя build_query(), можно легко создавать сложные URL-запросы, интегрировать API и передавать параметры между страницами.