http_build_query() 함수 사용법

http_build_query() 함수는
배열 또는 객체를 URL에서 사용할 수 있는 형식으로 인코딩하여 쿼리 문자열을 생성하는 함수입니다.

PHP 
$data = array(
    'name' => 'John Doe',
    'age' => 30,
    'city' => 'New York'
);

$queryString = http_build_query($data);
echo $queryString;

// 출력: name=John+Doe&age=30&city=New+York

http_build_query() 함수는 HTTP 요청을 생성하거나 URL을 만들 때 유용하게 사용됩니다. 주로 웹 애플리케이션에서 GET 요청을 생성하거나 API 호출을 할 때 많이 활용됩니다.

http_build_query() 함수의 형식은 다음과 같습니다.

구문

PHP 
http_build_query(
    array|object $data,
    string $numeric_prefix = "",
    ?string $arg_separator = null,
    int $encoding_type = PHP_QUERY_RFC1738
): string

매개변수

$data

URL에서 사용할 수 있는 형식으로 인코딩하여 쿼리 문자열을 생성할 배열 또는 객체입니다.

  • $data가 배열인 경우 간단한 1 차원 구조이거나 다른 배열을 포함할 수 있는 배열의 배열일 수 있습니다.
  • $data가 객체인 경우 public 속성만 결과에 통합됩니다.

$numeric_prefix

만약 기본 배열에 숫자 인덱스가 사용되고 이 매개변수가 제공된다면, 이는 기본 배열의 요소에만 숫자 인덱스 앞에 추가됩니다. 기본 값은 빈 문자열 ("")입니다.

이는 PHP나 다른 CGI 응용 프로그램에서 데이터를 나중에 디코딩할 때 유효한변수 이름을 허용하기 위한 것입니다.

예를 들어, 다음과 같은 배열이 있다고 가정해 보겠습니다.

PHP 
$data = array(
    1 => 'foo',
    2 => 'bar',
    3 => 'baz',
);

$queryString = http_build_query($data, 'my_');
echo $queryString;

이 배열을 http_build_query() 함수에 전달하고 두 번째 인수로 my_를 설정하면 다음과 같은 쿼리 문자열이 생성됩니다.

두 번째 인수로 'my_'를 설정

숫자 인덱스 이름 앞에 my_ 접두어가 추가되어 PHP 또는 다른 CGI 응용 프로그램에서 변수 이름으로 사용할 수 있습니다. 두 번째 인수를 설정하지 않으면 숫자 인덱스 이름은 그대로 유지됩니다.

$arg_separator

키-값 쌍을 구분하는 인수 구분자입니다. PHP의 arg_separator.output 설정값을 사용합니다. arg_separator.output의 값은 PHP의 php.ini 파일에 설정된 값입니다. 기본으로 설정된 값은 앰퍼샌드(&)입니다. 인수를 null로 설정하면 키-값 쌍을 구분하지 않습니다. 즉 구분자를 생성하지 않습니다.

예를 들어, 다음과 같은 배열이 있다고 가정해 보겠습니다.

PHP 
$data = array(
    'foo' => 'bar',
    'baz' => 'boom',
    'cow' => 'milk',
);

이 배열을 http_build_query() 함수에 전달하고 세 번째 인수를 설정하지 않으면 다음과 같은 쿼리 문자열이 생성됩니다. 기본 구분자인 앰퍼샌드(&)가 생성됩니다.

세 번째 인수를 설정하지 않았을 경우

세 번째 인수로 null 설정하면 다음과 같은 쿼리 문자열이 생성됩니다. 구분자를 생성하지 않습니다.

세 번째 인수를 null로 설정

세 번째 인수로 쉼표(,)를 설정하면 다음과 같은 쿼리 문자열이 생성됩니다.

세 번째 인수로 쉼표(,)를 설정

세 번째 인수로 세미콜론(;)을 설정하면 다음과 같은 쿼리 문자열이 생성됩니다.

세 번째 인수로 세미콜론(;)을 설정

$encoding_type

인코딩 형식을 설정합니다. 기본 값은 PHP_QUERY_RFC1738입니다.

  • PHP_QUERY_RFC1738은 PHP에서 제공하는 상수로 이 상수로 지정하면 RFC 1738과 application/x-www-form-urlencoded 미디어 타입에 따라 인코딩을 수행합니다. urlencode() 함수처럼 알파벳 대소문자, 숫자, -, _, . 문자를 제외한 문자를 % 기호와 16진수 코드로 인코딩됩니다. 공백은 공백을 +로 인코딩됩니다.
  • PHP_QUERY_RFC3986은 PHP에서 제공하는 상수로 이 상수로 지정하면 RFC 3986에 따라 인코딩을 수행합니다. rawurlencode() 함수처럼 알파벳 대소문자, 숫자, -, ., _, ~ 문자를 제외한 문자를 % 기호와 16진수 코드로 인코딩됩니다. 공백은 %20으로 인코딩됩니다.

예를 들어, 다음과 같은 배열이 있다고 가정해 보겠습니다.

PHP 
$data = array(
    'name' => 'John Doe',
    'age' => 30,
    'city' => 'New York'
);

이 배열을 http_build_query() 함수에 전달하고 네 번째 인수로 PHP_QUERY_RFC1738을 설정하면 다음과 같은 쿼리 문자열이 생성됩니다.

네 번째 인수로 PHP_QUERY_RFC1738을 설정

공백이 + 기호로 인코딩되었습니다.

네 번째 인수를 PHP_QUERY_RFC3986으로 설정하면 다음과 같은 쿼리 문자열이 생성됩니다.

PHP 
$data = array(
    'name' => 'John Doe',
    'age' => 30,
    'city' => 'New York'
);

$queryString = http_build_query($data, '', '&',  PHP_QUERY_RFC3986);
echo $queryString;
네 번째 인수를 PHP_QUERY_RFC3986으로 설정

공백이 %20으로 인코딩되었습니다.

예시 사용법

다음의 예시를 통해서 http_build_query() 함수의 사용법을 살펴보겠습니다.

HTTP GET 요청을 생성하는 경우

웹 애플리케이션에서 서버로 데이터를 전달하기 위해 HTTP GET 요청을 생성해야 할 때 http_build_query() 함수가 유용합니다. 예를 들어, 검색어나 필터링 조건을 URL에 포함하여 서버로 전송할 때 사용할 수 있습니다.

PHP 
$params = array(
    'search_query' => 'keyword',
    'category' => 'books',
    'sort' => 'relevance'
);

$query_string = http_build_query($params);
$url = 'https://example.com/search?' . $query_string;

// 이제 $url은 "https://example.com/search?search_query=keyword&category=books&sort=relevance"와 같은 형태가 됩니다.

API 요청을 생성하는 경우

원격 API에 요청을 보낼 때, API 엔드포인트 및 요청 매개변수를 포함하는 URL을 생성할 수 있습니다.

PHP 
$api_endpoint = 'https://api.example.com/data';
$api_key = 'your_api_key';
$params = array(
    'api_key' => $api_key,
    'action' => 'get_data',
    'format' => 'json'
);

$api_url = $api_endpoint . '?' . http_build_query($params);

// $api_url은 "https://api.example.com/data?api_key=your_api_key&action=get_data&format=json"와 같은 형태가 됩니다.

HTML 양식 요소의 액션 속성을 생성하는 경우

웹 양식을 만들 때 action 속성에 URL을 설정해야 하는데, http_build_query() 함수를 사용하여 양식 데이터를 URL에 포함할 수 있습니다.

PHP 
$form_data = array(
    'username' => 'user123',
    'password' => 'secret',
    'remember' => 1
);

$action_url = 'https://example.com/login?' . http_build_query($form_data);

// https://example.com/login?username=user123&password=secret&remember=1
// 이제 HTML 양식의 <form> 요소의 action 속성에 $action_url을 설정할 수 있습니다.

참고문헌

같이 보기