URL エンコードされたクエリ文字列を生成する

# http_build_query

(PHP 5, PHP 7, PHP 8)

http_build_query — URL エンコードされたクエリ文字列を生成する

### 説明

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

与えられた連想配列 (もしくは添字配列) から URL エンコードされたクエリ文字列を生成します。

### パラメータ

`data`

  プロパティを含む配列もしくはオブジェクト。

  `data` が配列の場合の形式は、 単純な一次元構造か あるいは配列の配列 (言い換えると、他の配列を含む配列) となります。

  `data` がオブジェクトの場合、 public プロパティだけが結果に含められます。

  > 注意: オブジェクトが評価される際に __toString() マジックメソッドが 呼び出されることはありません。クエリ文字列でオブジェクトの文字列表現を 使用するには、オブジェクトを明示的に文字列にキャストする必要があります。

`numeric_prefix`

  情報源となる配列 (`data` で指定した配列) に数値インデックスが使われていて、しかも `numeric_prefix` が指定された場合、数値のインデックスを持つ要素に関してのみインデックスの前に `numeric_prefix` で指定した値が付加されます。

  これは、後で PHP や他の CGI アプリケーションによってデータがデコードされる際、 正当な変数名になるよう考慮したものです。

`arg_separator`

  引数のセパレータ。指定されていなかったり、`null` だった場合は、 arg_separator.output が区分のためのセパレータとして使用されます。

`encoding_type`

  デフォルトは `PHP_QUERY_RFC1738` です。

  `encoding_type` が `PHP_QUERY_RFC1738` の場合は » RFC 1738 に従ってエンコードされ、メディアタイプは `application/x-www-form-urlencoded` となります。 つまり、スペースはプラス記号 (`+`) にエンコードされるということです。

  `encoding_type` が `PHP_QUERY_RFC3986` の場合は » RFC 3986 に従ってエンコードされ、 スペースはパーセント形式 (`%20`) となります。

### 戻り値

URL エンコードされた文字列を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | PHP 8.4.0 より前のバージョンでは、 `data` の BackedEnum プロパティは、 スカラー値ではなくオブジェクトに変換されていました。
8.0.0 | `arg_separator` は、nullable になりました。

### 例

例1 http_build_query() の簡単な使用法

    <?php
    $data = array(
        'foo' => 'bar',
        'baz' => 'boom',
        'cow' => 'milk',
        'null' => null,
        'php' => 'hypertext processor'
    );

    echo http_build_query($data) . "\n";
    echo http_build_query($data, '', '&amp;');

    ?>

上の例の出力は以下となります。

    foo=bar&baz=boom&cow=milk&php=hypertext+processor
    foo=bar&amp;baz=boom&amp;cow=milk&amp;php=hypertext+processor

例2 数値インデックス要素の場合での http_build_query()

    <?php
    $data = array('foo', 'bar', 'baz', null, 'boom', 'cow' => 'milk', 'php' => 'hypertext processor');

    echo http_build_query($data) . "\n";
    echo http_build_query($data, 'myvar_');
    ?>

上の例の出力は以下となります。

    0=foo&1=bar&2=baz&4=boom&cow=milk&php=hypertext+processor
    myvar_0=foo&myvar_1=bar&myvar_2=baz&myvar_4=boom&cow=milk&php=hypertext+processor

例3 複雑な配列の場合での http_build_query()

    <?php
    $data = array(
        'user' => array(
            'name' => 'Bob Smith',
            'age'  => 47,
            'sex'  => 'M',
            'dob'  => '5/12/1956'
        ),
        'pastimes' => array('golf', 'opera', 'poker', 'rap'),
        'children' => array(
            'bobby' => array('age'=>12, 'sex'=>'M'),
            'sally' => array('age'=>8, 'sex'=>'F')
        ),
        'CEO'
    );

    echo http_build_query($data, 'flags_');
    ?>

上の例は以下を出力します: (可読性のため適宜折り返しています)

    user%5Bname%5D=Bob+Smith&user%5Bage%5D=47&user%5Bsex%5D=M&
    user%5Bdob%5D=5%2F12%2F1956&pastimes%5B0%5D=golf&pastimes%5B1%5D=opera&
    pastimes%5B2%5D=poker&pastimes%5B3%5D=rap&children%5Bbobby%5D%5Bage%5D=12&
    children%5Bbobby%5D%5Bsex%5D=M&children%5Bsally%5D%5Bage%5D=8&
    children%5Bsally%5D%5Bsex%5D=F&flags_0=CEO

> 注意:

> 基底の配列内の数値インデックス要素 "CEO" のみ、 接頭辞を受け取ります。pastimes 以下にある他の数値インデックスは、 正当な変数名にするための文字列の接頭辞を要求しません。

例4 オブジェクトの場合の http_build_query() の使用

    <?php
    class parentClass {
        public    $pub      = 'publicParent';
        protected $prot     = 'protectedParent';
        private   $priv     = 'privateParent';
        public    $pub_bar  = null;
        protected $prot_bar = null;
        private   $priv_bar = null;

        public function __construct(){
            $this->pub_bar  = new childClass();
            $this->prot_bar = new childClass();
            $this->priv_bar = new childClass();
        }
    }

    class childClass {
        public    $pub  = 'publicChild';
        protected $prot = 'protectedChild';
        private   $priv = 'privateChild';
    }

    $parent = new parentClass();

    echo http_build_query($parent);
    ?>

上の例の出力は以下となります。

    pub=publicParent&pub_bar%5Bpub%5D=publicChild

例5 __toString() を含むオブジェクトでの http_build_query() の使用

    <?php
    class Foo {
        public $publicProperty = 'visible';

        public function __toString() {
            return "bar";
        }
    }

    $params = array(
        'a' => 'b',
        'foo' => new Foo()
    );

    // キャストしない場合、http_build_query は public プロパティを読み取ります
    echo http_build_query($params) . "\n";

    // 明示的にキャストすると、http_build_query は __toString() の出力を使用します
    $params['foo'] = (string) new Foo();
    echo http_build_query($params) . "\n";
    ?>

上の例の出力は以下となります。

    a=b&foo%5BpublicProperty%5D=visible
    a=b&foo=bar

### 参考

- parse_str() - URL のクエリストリングとして文字列をパースする
- parse_url() - URL を解釈し、その構成要素を返す
- urlencode() - 文字列を URL エンコードする
- array_walk() - 配列の全ての要素にユーザー定義の関数を適用する

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open