【PHP8.x】http_build_query()関数の使い方

Copy
1<?php
2
3/**
4 * 配列をクエリ文字列に変換し、それを元の配列に戻す例
5 */
6
7// 元の配列データ
8$data = [
9    'name' => 'John Doe',
10    'age' => 30,
11    'city' => 'New York'
12];
13
14// http_build_query() を使用してクエリ文字列を生成
15$query_string = http_build_query($data);
16
17echo "生成されたクエリ文字列: " . $query_string . PHP_EOL;
18
19// parse_str() を使用してクエリ文字列を配列に戻す
20parse_str($query_string, $result);
21
22echo "parse_str() で配列に戻した結果:". PHP_EOL;
23print_r($result);
24
25// オブジェクトの場合
26$object = (object) [
27    'name' => 'Jane Doe',
28    'age' => 25,
29    'city' => 'Los Angeles'
30];
31
32$query_string_from_object = http_build_query($object);
33
34echo "オブジェクトから生成されたクエリ文字列: " . $query_string_from_object . PHP_EOL;
35
36parse_str($query_string_from_object, $result_from_object);
37
38echo "parse_str() でオブジェクトから配列に戻した結果:". PHP_EOL;
39print_r($result_from_object);

http_build_query関数は、PHPのextensionで提供される関数の一つで、配列やオブジェクトをURLエンコードされたクエリ文字列に変換するために使用します。引数$dataに変換したい配列またはオブジェクトを渡します。$numeric_prefixは、数値キーを持つ配列要素のキーの前に付加するプレフィックスを指定します（省略可）。$arg_separatorは、引数セパレータを指定します（省略可、デフォルトは &）。$encoding_typeは、URLエンコードのタイプを指定します（省略可、デフォルトは PHP_QUERY_RFC1738）。

このサンプルコードでは、まず連想配列$dataをhttp_build_query()関数を使ってクエリ文字列に変換しています。生成されたクエリ文字列はname=John+Doe&age=30&city=New+Yorkのようになります。

次に、parse_str()関数を使って、生成されたクエリ文字列を元の配列に戻しています。parse_str()関数は、クエリ文字列を解析し、結果を配列に格納します。

同様に、オブジェクトをhttp_build_query()関数に渡してクエリ文字列を生成し、parse_str()関数で配列に戻す例も示しています。このように、http_build_query関数は配列だけでなくオブジェクトも処理できます。

http_build_query関数の戻り値は、生成されたクエリ文字列です。この関数とparse_str関数を組み合わせることで、配列とクエリ文字列を相互に変換することが可能です。これは、GETリクエストの作成や、セッションデータの保存など、様々な場面で役立ちます。

Copy
1<?php
2
3/**
4 * http_build_query と json_encode の使い分けを示すサンプル.
5 */
6function demonstrateQueryBuilderVsJsonEncoder(): void
7{
8    $data = [
9        'name' => '太郎',
10        'age' => 30,
11        'city' => '東京',
12        'skills' => ['PHP', 'JavaScript', 'MySQL']
13    ];
14
15    // http_build_query を使用して URL エンコードされた文字列を生成
16    $query = http_build_query($data);
17    echo "http_build_query: " . $query . PHP_EOL;
18
19    // URLのskillsパラメータを展開して表現
20    $query_expanded = http_build_query($data, '', '&', PHP_QUERY_RFC3986);
21    echo "http_build_query (RFC3986): " . $query_expanded . PHP_EOL;
22
23    // json_encode を使用して JSON 文字列を生成
24    $json = json_encode($data, JSON_UNESCAPED_UNICODE);
25    echo "json_encode: " . $json . PHP_EOL;
26
27    // json_encodeされたデータをデコード
28    $decoded_json = json_decode($json, true);
29    echo "json_decode: " . PHP_EOL;
30    print_r($decoded_json);
31}
32
33demonstrateQueryBuilderVsJsonEncoder();

http_build_query関数は、PHPで配列やオブジェクトをURLエンコードされたクエリ文字列に変換するために使用されます。この関数は、Web APIへのリクエストやURLパラメータの作成に役立ちます。第一引数$dataには、変換したい配列またはオブジェクトを指定します。第二引数$numeric_prefixは、数値キーを持つ要素のプレフィックスを指定する場合に使用します。第三引数$arg_separatorは、引数を区切る文字を指定します。デフォルトは&です。第四引数$encoding_typeは、エンコードタイプを指定します。PHP_QUERY_RFC1738（デフォルト）またはPHP_QUERY_RFC3986を指定できます。

このサンプルコードでは、http_build_queryとjson_encodeの使い分けを示しています。http_build_queryは、連想配列をURLエンコードされた文字列に変換します。一方、json_encodeは、配列をJSON形式の文字列に変換します。json_encodeを使用すると、複雑なデータ構造を表現できます。また、JSON_UNESCAPED_UNICODEオプションを使用することで、日本語などのUnicode文字をエスケープせずにJSON文字列に含めることができます。json_decode関数は、JSON形式の文字列をPHPの配列に変換します。 http_build_query関数を使用することで、URLに含めるパラメータを簡単に生成できます。

Copy
1<?php
2
3/**
4 * http_build_query関数の基本的な使用例
5 * 配列をURLエンコードされたクエリ文字列に変換します。
6 * システムエンジニアを目指す初心者にも理解しやすいように、一般的な使用方法を示します。
7 */
8
9// URLクエリ文字列に変換したいデータを連想配列として定義
10// ここでは、Webフォームの送信データやAPIリクエストのパラメータを想定しています。
11$params = [
12    'name' => '山田 太郎', // 日本語も自動的にURLエンコードされます
13    'email' => 'taro.yamada@example.com',
14    'age' => 30,
15    'interests' => ['プログラミング', '読書'], // 配列内の配列も適切に処理されます
16    'options' => [
17        'newsletter' => true, // 真偽値は 1 または 0 に変換されます
18        'notifications' => false,
19    ],
20    // 数値キーの配列も処理されますが、通常は連想配列を使用することが多いです
21    // 'items' => ['apple', 'banana'],
22];
23
24// http_build_query関数を呼び出して、配列をクエリ文字列に変換します。
25//
26// 引数:
27// 1. $data (array|object): 変換したい配列またはオブジェクト。
28// 2. $numeric_prefix (string, オプション): 数値キーに付加するプレフィックス。通常は空文字 ('') を指定します。
29// 3. $arg_separator (string|null, オプション): 引数間のセパレータ。null の場合、デフォルトの '&' が使用されます。
30// 4. $encoding_type (int, オプション): エンコーディングの種類。PHP_QUERY_RFC1738 (デフォルト) が一般的です。
31$queryString = http_build_query($params);
32
33echo "生成されたURLクエリ文字列:\n";
34echo $queryString . "\n\n";
35
36// 生成されたクエリ文字列を実際のURLに組み込む例
37$baseUrl = 'https://api.example.com/search';
38$fullUrl = $baseUrl . '?' . $queryString;
39
40echo "完全なURLの例:\n";
41echo $fullUrl . "\n";
42
43/*
44上記のコードを実行すると、以下のような出力が得られます：
45
46生成されたURLクエリ文字列:
47name=%E5%B1%B1%E7%94%B0+%E5%A4%AA%E9%83%8E&email=taro.yamada%40example.com&age=30&interests%5B0%5D=%E3%83%97%E3%83%AD%E3%82%B0%E3%83%A9%E3%83%9F%E3%83%B3%E3%82%B0&interests%5B1%5D=%E8%AA%AD%E6%9B%B8&options%5Bnewsletter%5D=1&options%5Bnotifications%5D=0
48
49完全なURLの例:
50https://api.example.com/search?name=%E5%B1%B1%E7%94%B0+%E5%A4%AA%E9%83%8E&email=taro.yamada%40example.com&age=30&interests%5B0%5D=%E3%83%97%E3%83%AD%E3%82%B0%E3%83%A9%E3%83%9F%E3%83%B3%E3%82%B0&interests%5B1%5D=%E8%AA%AD%E6%9B%B8&options%5Bnewsletter%5D=1&options%5Bnotifications%5D=0
51*/

PHPのhttp_build_query関数は、配列やオブジェクトをURLエンコードされたクエリ文字列に変換するために使われます。Webフォームの送信データやAPIリクエストのパラメータなど、プログラムで扱うデータをURLに含める形式に簡単に整形できます。

このサンプルコードでは、名前やメールアドレス、年齢、趣味などの情報を含む連想配列$paramsを用意しています。http_build_query関数にこの配列を渡すと、name=%E5%B1%B1%E7%94%B0+%E5%A4%AA%E9%83%8E&email=taro.yamada%40example.com&age=30...のようなURLクエリ文字列が生成されます。日本語などの特殊文字は自動的にURLエンコードされ、配列内の配列や真偽値も適切に処理されてクエリ文字列に組み込まれます。

関数の第一引数$dataには、変換したい配列やオブジェクトを指定します。この関数は、URLエンコードされたクエリ文字列を文字列として返します。$numeric_prefix、$arg_separator、$encoding_typeといったオプションの引数もありますが、これらは通常、デフォルトの挙動で利用されることがほとんどです。

生成されたクエリ文字列は、ベースとなるURLに続けて結合することで、APIリクエストなどに利用する完全なURLを簡単に構築できます。これにより、複雑なパラメータをURLとして安全かつ正確に渡すことが可能になります。

Copy
1<?php
2
3/**
4 * http_build_query 関数の使用例を示します。
5 * この関数は、データ配列からURLエンコードされたクエリ文字列を生成します。
6 * キーワード「without url encoding」に関して、http_build_query は常に値をURLエンコードしますが、
7 * `encoding_type` パラメータによってスペースのエンコード形式を制御できます。
8 * PHP_QUERY_RFC1738 (デフォルト) はスペースを '+' に、PHP_QUERY_RFC3986 はスペースを '%20' にエンコードします。
9 */
10function buildAndDisplayQueryStrings(): void
11{
12    // クエリ文字列に変換するデータ
13    $data = [
14        'name' => 'John Doe',
15        'city' => 'New York',
16        'query' => 'search for spaces & special chars',
17        'tags' => ['php', 'web development'],
18    ];
19
20    echo "--- デフォルトのエンコーディング (PHP_QUERY_RFC1738) ---\n";
21    // デフォルトのエンコーディング (PHP_QUERY_RFC1738): スペースは '+' にエンコードされます。
22    $defaultEncodedQuery = http_build_query($data);
23    echo "出力 (RFC1738): " . $defaultEncodedQuery . "\n\n";
24
25    echo "--- RFC 3986 形式のエンコーディング (PHP_QUERY_RFC3986) ---\n";
26    // RFC 3986 形式のエンコーディング: スペースは '%20' にエンコードされます。
27    // 「URLエンコーディングなし」という意図が、RFC 1738の '+' ではなく '%20' を望む場合、
28    // このオプションが最も関連します。完全にエンコーディングをしないわけではありません。
29    $rfc3986EncodedQuery = http_build_query($data, '', null, PHP_QUERY_RFC3986);
30    echo "出力 (RFC3986): " . $rfc3986EncodedQuery . "\n\n";
31
32    echo "--- 注意点 ---\n";
33    echo "http_build_query 関数は、引数の値を常にURLエンコードします。\n";
34    echo "「URLエンコーディングなし」という要件は、この関数では直接達成できません。\n";
35    echo "encoding_type パラメータは、主にスペースのエンコード形式を制御するためのものです。\n";
36    echo "その他の特殊文字 ('&', '=', '/', '?') などは、どちらの形式でもURLエンコードされます。\n";
37}
38
39// 関数を実行して結果を表示
40buildAndDisplayQueryStrings();

http_build_query関数は、PHPで連想配列やオブジェクトのデータを、URLのクエリ文字列形式に変換するために使用します。例えば、ウェブサイトで検索条件をURLに含めたり、APIへリクエストを送る際のパラメータを生成したりする際に便利です。

この関数は、第一引数 $data に指定された配列やオブジェクトの各要素を「キー=値」の形式で連結し、それらをアンパサンド (&) で区切って一つの文字列として返します。このとき、自動的にURLエンコードが行われます。

第四引数 $encoding_type を使用することで、スペース文字のエンコード形式を制御できます。デフォルトでは PHP_QUERY_RFC1738 が適用され、スペースは + に変換されます。一方、PHP_QUERY_RFC3986 を指定すると、スペースは %20 としてエンコードされます。

サンプルコードでは、同じデータに対してこれら二つのエンコーディングタイプを適用し、その結果の違いを示しています。これにより、クエリ文字列内のスペースがどのように変換されるかを確認できます。この関数は、引数の値を常にURLエンコードするため、「URLエンコーディングなし」という要件を直接満たすことはできません。encoding_typeは主にスペースの扱いを調整するためのものであり、その他の特殊文字はどちらのエンコーディングタイプでも適切にURLエンコードされる点にご注意ください。