【PHP8.4】PUTやPATCHでもリクエストボディを簡単に取得できるようになる

PHPでは、POSTでリクエストを送るとリクエストボディが自動的に[スーパーグローバル変数`$_POST`に格納されます](https://www.php.net/manual/ja/reserved.variables.post.php)。

これは非常に便利なのですが、注意点としてPOSTでないかぎり入ってきません。
たとえリクエストメソッドGETやPUTにリクエストボディを入れて送ったとしても`$_POST`は空です。

そしてPHPには何気にリクエストボディをパースする関数がなく、自力でパースするのは[たいへんに面倒で誤りも入りがち](https://stackoverflow.com/questions/5483851/manually-parse-raw-multipart-form-data-data-with-php)です。

この対応案としてスーパーグローバル変数`$_PUT`を追加したいみたいな話が出たこともあるのですが、それでは`$_PATCH`とか`$_DELETE`とかも必要なのかということになってあまり現実的ではないでしょう。

ということで、リクエストメソッドに関わらずリクエストボディを取得する関数`request_parse_body()`のRFCが提出されました。
既に受理されており、PHP8.4から利用可能になります。

以下は該当のRFC、[RFC1867 for non-POST HTTP verbs](https://wiki.php.net/rfc/rfc1867-non-post)の紹介です。

# PHP RFC: RFC1867 for non-POST HTTP verbs

## Proposal

`multipart/form-data`コンテンツタイプはRFC1867で定義されています。
このコンテンツタイプは主に、ファイルを含むHTTPフォームで使用されています。
PHPは、このコンテンツタイプのパースをネイティブでサポートしていますが、しかしそれはPOSTリクエストに対してだけです。
具体的には、リクエストメソッドがPOSTかつコンテンツタイプが`multipart/form-data`である場合に、PHPはリクエストボディをパースして`$_POST`と`$_FILES`スーパーグローバル変数に代入します。
この機能は裏側で自動的にトリガーされており、ユーザランドには公開されません。

RESTの出現により、PHPが対応していないPUTやPATCHなどのリクエストメソッドの利用が一般的になりました。
しかしこれらのリクエストメソッドを使用するには、リクエストボディを手動で解析しなければなりません。
ユーザランドによる実装は、データ量を考えるとパフォーマンスの点で適切ではないでしょう。
[Issue](https://bugs.php.net/bug.php?id=55815)には350以上のupvoteが投じられています。

このRFCでは、リクエストボディを取得する関数`request_parse_body`を追加し、既存のパース機能をユーザランドから使えるようにします。

```php
/**
 * @param array<string, int>|null $options
 */
function request_parse_body(?array $options = null): array {}
 
// PUTリクエストだった場合$_POSTも$_FILESも入ってこない
var_dump($_POST);  // []
var_dump($_FILES); // []
 
[$_POST, $_FILES] = request_parse_body();
 
var_dump($_POST);  // [...]
var_dump($_FILES); // [...]
```

この関数は`[0=>POST, 1=>FILES]`の配列を返します。
必要に応じて、返り値でスーパーグローバル変数`$_POST`および`$_FILES`を上書きできます。
これによって既存の`$_POST`を再利用可能となります。

この関数は`sapi_module.read_post()`から入力を取得します。

### Sanitization

自動呼び出しの場合と同じく、`request_parse_body()`は幾つかの原因でマルチパート解析に失敗します。

・入力サイズがpost_max_sizeを超えた。
・Content-Typeにboundaryが設定されていない。
・マルチパート数がmax_multipart_body_partsを超えた。
・POST入力数がmax_input_varsを超えた。
・送信ファイル数がmax_file_uploadsを超えた。
・ファイルにnameもfilenameも設定されていない。

解析に失敗すると警告が発生します。
また新しい例外RequestParseBodyExceptionが実装され、解析エラーを例外でキャッチできるようになります。

`request_parse_body()`は冪等ではないことに注意してください。
`request_parse_body()`を2回呼び出すことは安全ではありません。
これについては下記`php://input`セクションで詳しく説明します。


### Supported content types

このRFCが建てられた目的は`multipart/form-data`ですが、同時に`application/x-www-form-urlencoded`コンテンツタイプもサポートします。
`application/x-www-form-urlencoded`の場合、`$_FILES`相当部分は空です。
サポートされていないコンテンツタイプにはInvalidArgumentExceptionが発生します。


### php://input

リクエストコンテンツには通常、`php://input`ストリームでアクセスできます。
このストリームは入力をバッファリングしており、何度でも読み込むことが可能です。
リクエストメソッドがPOSTだった場合、PHPは制御をスクリプトに渡す前にリクエストボディ全体を読み取ってバッファリングします。
POST以外では、事前にリクエストボディを読み込むことはありません。
入力ストリームを読み込もうとしたときに初めてバッファリングされます。

このバッファリングメカニズムの唯一の例外が`multipart/form-data`であり、ストリームは空になります。
この理由として、パースした結果は`$_POST`と`$_FILES`から利用できるため、ストリームを使う必要がないということが挙げられます。
これらのリクエストをバッファリングするということは、全てのリクエストボディをスーパーグローバル変数とストリームバッファの2個所に保存することになるため、時間とディスクスペースの負担が2倍になることを意味します。

同じ理由で、`request_parse_body()`はバッファリングを行いません。
この関数は`sapi_module.read_post()`を破壊的に消費するため、2回目の呼び出しはできないことになります。

### $options parameter

グローバルではなくエンドポイント単位で入力制限をカスタマイズできます。
たとえばログイン者限定のフォームがあるとして、入力制限を`post_max_size`や`upload_max_filesize`で緩和すると、DoS攻撃などのリスクが高まる可能性があります。
従って、特定のエンドポイントについてのみ、これらの制限を変更できる方が好ましいでしょう。

`request_parse_body()`は、第二引数`$option`で次のini設定をオーバーライドするかのように動作します。

・max_file_uploads
・max_input_vars
・max_multipart_body_parts
・post_max_size
・upload_max_filesize

```php
#[Route('/api/videos', methods: ['PUT'])]
public function index(): Response {
    [$post, $files] = request_parse_body(options: [
        'post_max_size' => '128M',
    ]);
 
    // ...
}
```

無効なキーや値を指定するとValueErrorが発生します。


### Why not parse the content automatically?

POSTリクエストは`application/x-www-form-urlencoded`や`multipart/form-data`を自動的にパースするのに、PUTやPATCHやその他の動詞では同じように動作しないのはなぜでしょうか。
主な理由はふたつあります。

一つ目は下位互換性です。
multipartのリクエストでは、リクエストボディはバッファリングされず消費されます。
マルチパートを手動で解析している既存コードは、入力ストリームが取得できなくなるため壊れてしまいます。

もうひとつの理由は、柔軟性が向上することです。
multipartを受け入れないエンドポイントは、リクエストを解析することなく早期に終了することがあるでしょう。
その場合にわざわざリクエストボディをパースしてバッファリングし、全く使用せずにファイルを削除するという手間を省くことができます。

なお、POSTリクエストでもこの利点を享受したい場合は、ini設定[enable_post_data_reading](https://www.php.net/manual/ja/ini.core.php#ini.enable-post-data-reading)で変更可能です。


## Backwards incompatible changes

グローバル名前空間で`request_parse_body()`と`RequestParseBodyException`が予約されます。
他に後方互換性のない変更はありません。


## RFC1867 refresher

RFC1867のおさらい。

RFC1867は`multipart/form-data`コンテンツタイプの定義です。
このコンテンツタイプは、主にファイルを含むHTTPリクエストを送信するために利用されます。
入力のキーと値のペアを送信する形式という意味では、`application/x-www-form-urlencoded`と似ています。
各入力は、他で使われていない任意の文字列で区切られます。
ファイルの場合、元のファイル名とコンテンツタイプも属性として渡されます。
以下に簡単な例を示します。

```
POST / HTTP/1.1
Host: localhost:9000
Content-Type: multipart/form-data; boundary=---------------------------84000087610663814162942123332

-----------------------------84000087610663814162942123332
Content-Disposition: form-data; name="post_field"

post content
-----------------------------84000087610663814162942123332
Content-Disposition: form-data; name="file_field"; filename="original_filename.txt"
Content-Type: text/plain

file content
-----------------------------84000087610663814162942123332--
```

PHPではスーパーグローバル変数`$_POST`・`$_FILES`に格納されます。

```php
var_dump($_POST);
array(1) {
  ["post_field"]=>
  string(9) "post data"
}

var_dump($_FILES);
array(1) {
  ["file_field"]=>
  array(6) {
    ["name"]=>
    string(21) "original_filename.txt"
    ["full_path"]=>
    string(21) "original_filename.txt"
    ["type"]=>
    string(10) "text/plain"
    ["tmp_name"]=>
    string(%d) "/tmp/sometmpfilename"
    ["error"]=>
    int(0)
    ["size"]=>
    int(12)
  }
}
```

RFC1867形式のリクエストは、リクエストメソッドがPOSTである場合は自動的に解析されます。
ファイル以外のリクエストボディは`$_POST`に登録されます。
ファイルの場合、コンテンツはテンポラリファイルに保存され、テンポラリファイルのパスと関連情報が`$_FILES`に渡されます。
またリクエストの最後に、テンポラリファイルは自動的に削除されます。
これによって、サーバのディスク領域を埋めようとする攻撃を防いでいます。


## Rejected ideas

拒否されたアイデア。

### $input_stream parameter

このRFCには、かつてRoadRunnerなど特殊なSAPIが使用することを想定した引数`$input_stream`が存在しました。
しかし詳しく調べてみたところ、RoadRunnerやFrankenPHPでは不要でした。

この引数が必要となりそうなものは、[Workerman](https://github.com/walkor/workerman)・[AdapterMan](https://github.com/joanhey/AdapterMan)などのPHP製Webサーバに限られるようです。
しかしそれらにおいては、リクエストはストリームではなく文字列で処理されています。
文字列ではなくストリームを使うようになったら、この引数を再度検討する余地はあるでしょう。


## Vote

投票期間は2023/01/22から2023/02/05、投票者の2/3の賛成で受理されます。
[とか書かれてる](https://wiki.php.net/rfc/rfc1867-non-post#vote)んだけど、おそらく2024年の間違いです。

本RFCは賛成23反対1の賛成多数で受理されました。

便利関数`request_parse_body()`が、PHP8.4から使用可能になります。


# 感想

[もっと正確かつ統一的にHTTPインターフェイスを扱おう](https://wiki.php.net/rfc/http-interface)というRFCがずっと前からあるのですが、こちらは放置で単純にリクエストボディを取得する関数になりました。
実際ユーザがやりたいことはリクエストの正しい解析なんかではなくリクエストを使って何かすることなので、妥当な方向性といえるでしょう。

この関数が役立つ場面はHTMLフォームではありません。
HTMLフォームではいまだにGET/POSTしか使えないし、今後も増える見込みはないので、特に関係ありません。

でも[LaravelにはPUTもDELETEもOPTIONSもあるじゃん？](https://laravel.com/docs/11.x/routing#available-router-methods)と思うかもしれませんが、実際はこれPOSTしつつ隠しパラメータで`_method=put`とか送っているだけという[なんちゃってPUT](https://qiita.com/Masahiro111/items/907aab0dc4ecd6015521)であり、実際はPOSTです。

この関数が必要となるのはHTMLフォーム以外からのリクエストであり、たとえば[fetch API](https://developer.mozilla.org/ja/docs/Web/API/Fetch_API)はPUT/DELETEといった既存リクエストメソッドや、さらに勝手に決めたオレオレリクエストメソッドなんてものも送ることができます。
そういったエンドポイントからのリクエストを簡単に受け取れるようになる、たいへん便利な関数ですね。

とはいえ実際ユーザが直接この関数を触ることはあんまりなくて、フレームワークが用意した`$request->method()`みたいなインターフェイスを使えばこれまでと全く同じ使い方ができるよ、みたいな方向になるとは思いますが。