TSとPHPでFormDataの型を共有する
背景
https://twitter.com/did0es/status/1401471990259613697
サーバーサイドで Node.js が動かない環境(某レンタルサーバー)でアプリケーションを実装する必要が生じたため、渋々 PHP を書いていたんですが、クライアントサイドは React で書きたいという我儘が出てきてしまい、その欲望に従った結果型を共有出来ないゆえの地獄を見たのでその脱出を図りました。
概観
筆者は FormData を扱う際に以下のような型の拡張を書いたd.tsファイルを使うことがあります。
append の name を文字列リテラルで縛っています。サーバーサイドも TypeScript の場合この型定義を共有することで、クライアントサイドから送信される FormData の name がどのようなものか簡単にわかるようになっています。また VSCode などでは補完機能により、タイポを防いで無駄な確認の手間を省くという意味合いもあります。
ただサーバーサイドが PHP の場合(TypeScript 以外の言語でもそうですが)、d.ts ファイルを共有出来ないため、何かしら別の手段を用意する必要があります。
今回は PHP なので、PHPDoc Types と PHPStan の静的解析による型チェックを活用していきます。
用意するもの
クライアントサイドは TypeScript で書かれている前提で、他にサーバーサイドでは以下のものを用意します。
どちらも composer でインストール出来ます。
実装
FormDataを拡張した型を取り出してJSONにする
FormData を拡張した型定義は以下のようになっています。
formdata.d.ts
上のコードから name の Parameters を取り出して JSON にします。数行程度で実装出来ます。
types-bridge/src/core.ts
visit関数によって型定義の TypeScript AST を Traverse し、該当する SyntaxKind を取り出してオブジェクトに格納しています。オブジェクトは後に PHP側 の実装と共有するため JSON として書き出しています。別に JSON じゃなくても PHP 側でも読み込めるファイルであればここは何でもいいです。
PHP側でJSONのデータをPHPDoc Typesに変換
POST された FormData は PHP 側で $_FILES から受け取ります。定義済み変数の型を拡張する方法がわからなかったので以下のようなクラスを定義しました。(こうすれば拡張できていいよ！とかあれば教えて下さい)
server/src/shared/http_variables.php
この状態で PHPStan を実行すると落ちます。(PHPStan の level は max で実行しています)
この PHPStan による型チェックが通ることをゴールに進めます。
files メソッドの @return の型はとりあえず以下のように設定しておきます。
@param の方は先程用意した JSON を元に作成します。以下が実際に実装したコードです。
server/scripts/types-bridge-client.php
PHP-Parser の PhpParser\\NodeTraverser を利用して、対象の PHP ファイルから files メソッドの PHPDoc Comment を探し出し、getDocComment で取り出しています。取り出したコメントは整形した後、@param の型に相当する部分を読み込んだ JSON を元に setDocComment で置き換えています。
試しにこの files メソッドの戻り値から目当ての値を呼び出してみます。
PHPStan による型チェックは通ります。
🎉
ちなみに呼び出す際の key を先程生成した PHPDoc Types に存在しないものにするとちゃんとチェックは落ちます。
おわりに
サーバーサイドが TypeScript でない状況でもどうにか AST の力を借りて型を共有してみました。
PHP の $_FILES 以外に $_GETや $_POST でも同様に拡張した型定義があれば FormData 以外でも PHP 側に型を流すことが出来ると思います。
実際に実装したリポジトリなどは公開していないのでお見せ出来ないんですが、何か質問やまさかりなどあれば shuta までお願いします。