Http build query: примеры (PHP)

Функция http_build_query в PHP: примеры применения
Раздел: URL
http_build_query(array|object $data, string $numeric_prefix = "", ?string $arg_separator = null, int $encoding_type = PHP_QUERY_RFC1738): string
типовые примерыhttp build query на js, python, mysqlhttp build query изменения phpпримеры расширенные

Описание функции http_build_query

Функция http_build_query преобразует массив или объект в строку запроса URL. Часто применяется при формировании GET-запросов, отправке данных через cURL или построении URL с параметрами.

Аргументы функции
  • $data - массив или объект с данными для преобразования
  • $numeric_prefix - префикс для числовых индексов, когда они не имеют именованных ключей
  • $arg_separator - разделитель аргументов (по умолчанию '&')
  • $encoding_type - тип кодирования: PHP_QUERY_RFC1738 (по умолчанию) или PHP_QUERY_RFC3986

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

Простой массив
$data = ['name' => 'Иван', 'age' => 30, 'city' => 'Москва'];
echo http_build_query($data);
name=%D0%98%D0%B2%D0%B0%D0%BD&age=30&city=%D0%9C%D0%BE%D1%81%D0%BA%D0%B2%D0%B0
С числовыми индексами
$data = [10, 20, 30];
echo http_build_query($data, 'num');
num0=10&num1=20&num2=30
Разные типы кодирования
$data = ['query' => 'тест пример'];
echo 'RFC1738: ' . http_build_query($data, '', '&', PHP_QUERY_RFC1738) . "\n";
echo 'RFC3986: ' . http_build_query($data, '', '&', PHP_QUERY_RFC3986);
RFC1738: query=%D1%82%D0%B5%D1%81%D1%82+%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80
RFC3986: query=%D1%82%D0%B5%D1%81%D1%82%20%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80

Похожие функции в PHP

urlencode()

Кодирует строку для использования в URL, но не работает с массивами. Применяется для отдельных значений.

urldecode()

Выполняет обратное преобразование декодируя строку URL.

parse_str()

Парсит строку запроса в массив, являясь обратной функцией для http_build_query.

http_build_url()

Доступна в PECL, создает полный URL из компонентов.

Аналоги в других языках

Python: urllib.parse.urlencode()
from urllib.parse import urlencode
data = {'name': 'Иван', 'age': 30}
print(urlencode(data))
name=%D0%98%D0%B2%D0%B0%D0%BD&age=30
JavaScript: URLSearchParams
const params = new URLSearchParams();
params.append('name', 'Иван');
params.append('age', 30);
console.log(params.toString());
name=%D0%98%D0%B2%D0%B0%D0%BD&age=30
MySQL: CONCAT_WS

Прямого аналога нет, но можно собрать строку запроса с помощью CONCAT_WS

Типичные ошибки

Неправильная обработка многомерных массивов
$data = ['user' => ['name' => 'Иван', 'age' => 30]];
echo http_build_query($data);
user%5Bname%5D=%D0%98%D0%B2%D0%B0%D0%BD&user%5Bage%5D=30

Результат может быть неожиданным без правильного декодирования.

Потеря данных при одинаковых ключах
$data = ['id' => 1, 'id' => 2];
echo http_build_query($data);
id=2

Последнее значение перезаписывает предыдущее.

Проблемы с кириллицей
$data = ['word' => 'пример'];
echo http_build_query($data, '', '&', PHP_QUERY_RFC1738);
word=%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80

Без указания кодировки могут возникать проблемы.

Изменения в новых версиях PHP

PHP 8.0

Функция теперь принимает объекты с любыми свойствами, а не только public. Добавлена поддержка интерфейса Stringable.

PHP 7.4

Улучшена обработка многомерных массивов и объектов.

PHP 5.4

Добавлен параметр $encoding_type с поддержкой PHP_QUERY_RFC3986.

Расширенные примеры

Сложные структуры данных
Пример php
$data = [
    'users' => [
        ['id' => 1, 'name' => 'Иван'],
        ['id' => 2, 'name' => 'Петр']
    ],
    'meta' => ['page' => 1, 'limit' => 20]
];
echo http_build_query($data);
users%5B0%5D%5Bid%5D=1&users%5B0%5D%5Bname%5D=%D0%98%D0%B2%D0%B0%D0%BD&users%5B1%5D%5Bid%5D=2&users%5B1%5D%5Bname%5D=%D0%9F%D0%B5%D1%82%D1%80&meta%5Bpage%5D=1&meta%5Blimit%5D=20
Работа с объектами
Пример php
class User {
    public $name = 'Иван';
    private $age = 30;
}
$user = new User();
echo http_build_query($user);
name=%D0%98%D0%B2%D0%B0%D0%BD
Кастомный разделитель
Пример php
$data = ['a' => 1, 'b' => 2];
echo http_build_query($data, '', ';');
a=1;b=2
Кодирование сложных символов
Пример php
$data = ['symbols' => 'a+b=c&d/e'];
echo http_build_query($data);
symbols=a%2Bb%3Dc%26d%2Fe
Исключение элементов
Пример php
$data = ['visible' => 'yes', 'secret' => 'no'];
$filtered = array_filter($data, fn($k) => $k !== 'secret', ARRAY_FILTER_USE_KEY);
echo http_build_query($filtered);
visible=yes

PHP http_build_query function comments

En
Http build query Generate URL-encoded query string