概念と使用方法

PHPバージョン
4+

parse_str() 関数は
URLで使用可能な形式にエンコードされたクエリ文字列をデコードして変数にパースするために使用する関数です。

この関数は結果を返すのではなく、第二引数として渡された変数にパースしたデータを配列形式で格納します。

主にhttp_build_query() 関数でエンコードされたクエリ文字列をデコードし、変数にパースするために使用されます。

http_build_query() 関数は
配列またはオブジェクトをURLで使用可能な形式にエンコードしてクエリ文字列を生成する関数です。

基本の例

PHP 
// URLで使用可能な文字列形式にエンコードする配列
$data = array(
    'name' => 'John Doe',
    'age' => 30,
    'city' => 'New York'
);

// http_build_query() 関数を使用してクエリ文字列にエンコード
$queryString = http_build_query($data);
echo $queryString; // 出力: name=John+Doe&age=30&city=New+York

// parse_str() 関数を使用してデコード
// パースしたデータを第二引数 $decodedArray に配列形式で格納
parse_str($queryString, $decodedArray);

print_r($decodedArray); // 出力: Array ( [name] => John Doe [age] => 30 [city] => New York )

parse_str() 関数は、URLで使用可能な形式にエンコードされたクエリ文字列をデコードして変数にパースするための関数です。主にhttp_build_query() 関数でエンコードされたURLクエリをデコードする際に使用されます。http_build_query() 関数は主に配列をURLクエリ文字列に変換する際に使用され、parse_str() 関数はそれをデコードする役割を担います。

parse_str() 関数は、http_build_query() 関数でエンコードされたURLクエリ文字列をデコードしてキーと値のペアに変換し、それを配列または変数に代入します。

したがって、parse_str() 関数とhttp_build_query() 関数は、互いに逆の役割を果たすと言えます。

構文

PHP 
parse_str(string $string, array &$result): void

引数

parse_str() 関数の引数
$string デコードする対象のエンコード済みURL文字列です。
&$result この引数を設定すると、デコードされたキーと値のペアが格納される配列です。参照変数になります。

戻り値

返り値はありません。

変更履歴

PHP 7.2.0以降、引数を指定せずにparse_str() 関数を使用することは推奨されていません。これは、この方法の使用がセキュリティ上のリスクとなる可能性があるためです。悪意のあるユーザーがURLエンコードされたクエリ文字列に挿入したコードが実行される可能性があります。

さらに、PHP 8.0.0以降では &$result 引数の指定が必須となるため、この関数を使用する際には必ず &$result 引数を提供する必要があります。

注意してください！
第二引数を使用せずにこの関数を使用することは非常に推奨されておらず、PHP 7.2.0以降では非推奨（DISCOURAGED）となり、PHP 8.0.0以降では第二引数 &$result が必須となります。

変更履歴
バージョン説明
8.0.0 &$result 引数はもはやオプションではなく、必須の引数です。
7.2.0 第二引数なしで parse_str() を使用すると、E_DEPRECATED 通知が発生します。

推奨方法と非推奨方法

parse_str() 関数は、URLクエリ文字列（例：name=John+Doe&age=30）をPHPの変数に解析するために使用されます。しかし、この関数は使用方法によって推奨される方法と非推奨の方法に分かれます。安全で予測可能なコードを作成するためには、推奨される方法を使用することが非常に重要です。

非推奨の方法：第二引数を省略する

parse_str() 関数に第二引数を省略し、クエリ文字列のみを渡す方法です。

PHP 
$query_string = 'name=John+Doe&age=30';

// 非推奨の方法：結果を格納する配列引数を省略
parse_str($query_string);

// $name と $age 変数が現在のスコープに直接生成されます
echo '名前（非推奨の方法）：' . $name . '<br>'; // 出力: '名前（非推奨の方法）：John Doe'
echo '年齢（非推奨の方法）：' . $age; // 出力: '年齢（非推奨の方法）：30'
なぜ非推奨なのでしょうか？
  • コードを読む人にとって、parse_str() 関数によってどの変数が突然生成されたのかを一目で把握することは難しくなります。
  • すでにコード内に $name という変数が存在する場合、parse_str() によって別の $name 変数が生成され、既存の変数の値を上書きしてしまう可能性があります。
  • PHP 7.2.0 以降では、このような使用方法に対して警告（E_DEPRECATED）が表示され始め、PHP 8.0.0 以降ではエラー（&$result 引数必須）が発生し、動作しなくなります。

推奨の方法：第二引数に配列を渡す

parse_str() 関数に、クエリ文字列とともにパースした結果を格納する配列変数を第二引数として渡す方法です。

PHP 
$query_string = 'name=John+Doe&age=30';

// 推奨の方法：結果を $parsed_data 配列に格納
$parsed_data = []; // 結果を格納する配列はあらかじめ宣言しておくことが望ましいです
parse_str($query_string, $parsed_data);

// パースされたデータは $parsed_data 配列内にあります
$name = $parsed_data['name'];
$age = $parsed_data['age'];

echo '名前（推奨の方法）：' . $name . '<br>'; // 出力: '名前（推奨の方法）：John Doe'
echo '年齢（推奨の方法）：' . $age; // 出力: '年齢（推奨の方法）：30'
なぜ推奨されるのでしょうか？
  • パースされたすべての結果が指定された一つの配列内にカプセル化されるため、外部からの入力がコード内の他の変数を勝手に生成したり上書きしたりすることを根本的に防ぐことができます。
  • コードを読む際に、parse_str() の結果が $parsed_data という特定の配列に格納されることがすぐに分かるため、コードの流れを理解しやすくなります。
  • 変数名の衝突を心配することなく、常に一貫した方法でデータにアクセスできるため、保守が容易になります。
  • PHP 8.0.0 以降のバージョンでも問題なく動作する、唯一かつ正しい使用方法です。

参考資料

関連項目