HaxeとPHPの境界線を破壊せよ：PHPStanを唸らせる型定義自動生成パイプラインの構築
HaxeをPHPターゲットで利用する際、多くの開発者が直面する「暗黒の壁」がある。それは、Haxeが吐き出すコードをPHPStanやPsalmが「正体不明の何か」として扱い、型推論を放棄することだ。
Haxeは強力な型システムを持つ。しかし、PHP側にその型情報を手動で定義し直すのは、Haxeを使う意義を根底から覆す徒労である。今日、我々が目指すのは、HaxeのソースコードからPHPスタブ（`.php`）を自動生成し、静的解析ツールを完全に掌握するビルドパイプラインの設計だ。
—
なぜ「そのまま」ではいけないのか
HaxeのPHPターゲットは、HaxeのコードをPHPのクラスとして出力するが、PHPの型システムとHaxeのそれは1対1ではない。特に複雑なジェネリクスや構造的部分型（Structural Typing）は、PHP側からは単なる `mixed` や `array` としてしか認識されない。
これを放置すれば、CI/CDでPHPStanがエラーを吐き、IDEは補完を失い、君のコードベースは「動くが脆い遺物」へと成り下がる。
アーキテクチャの戦略：マクロによるメタデータ抽出
解決策はシンプルだ。Haxeのビルドプロセスに「型定義抽出マクロ」を組み込み、コンパイル時にPHPスタブを生成させる。
以下のコードは、Haxeの `BuildMacro` を活用し、特定のクラスをPHPのスタブとして書き出すためのテンプレートだ。
if macro
import haxe.macro.Context;
import haxe.macro.Expr;
import sys.io.File;
class StubGenerator {
/
- コンパイル時に型情報を抽出し、PHPスタブを生成する
/
public static function generate() {
var localClass = Context.getLocalClass().get();
var className = localClass.name;
var output = ‘ int, String -> string 等
return “mixed”;
}
}
end
—
実務で勝つためのパイプライン構築術
このマクロを `build.hxml` に組み込むことで、ビルドと同時にスタブが生成される。このパイプラインの肝は以下の3点だ。
1. 疎結合なディレクトリ管理: `stubs/` ディレクトリをPHPStanの `scanDirectories` に登録する。これにより、Haxeで変更があるたびにPHP側の型情報も追従する。
2. 抽象型の活用: Haxeの `abstract` を利用して、PHPの特定の型（例：`DateTimeImmutable`など）へのマッピングを固定する。これにより、トランスパイル後の型安全性が担保される。
3. マクロのキャッシュ無効化: ビルド時に `Context.onMacroContext` を使い、Haxeのコンパイルプロセスと同期させる。
実践：PHPStanを黙らせるスタブ例
/
- Haxe側から自動生成されたスタブ
- @see Haxe source: MyService.hx
/
namespace App\Stubs;
class MyService {
/ @var string /
public string $id;
/ @param array
public function process(array $data): void {}
}
—
パフォーマンスと保守性のための注意点
- 不要なリフレクションを避ける: HaxeのPHPターゲットは `haxe.rtti.Meta` を多用しがちだが、本番環境ではランタイムのコストになる。スタブ生成はあくまで「開発時の解析支援」と割り切り、ランタイム用のコードには影響を与えないようコンパイル条件 (`#if !macro`) で厳格に分離せよ。
- 型変換のオーバーヘッド: Haxeの `Int` や `Float` はPHPのネイティブ型に変換されるが、複雑な構造体（`{x: Int, y: Int}`）をPHP側に渡す際は、一度 `stdClass` や連想配列へのシリアライズが必要になる。この境界線でのバリデーションを疎かにすると、PHP側で未知の `null` に遭遇する。
結論：HaxeはPHPの「最強の静的解析器」になれる
Haxeを単なるトランスパイラとして使うのは、フェラーリで近所のコンビニに行くようなものだ。
今回紹介した「型定義の自動生成」をパイプラインに組み込めば、PHPという動的言語の海の中で、Haxeという強力な羅針盤を手に入れることができる。
君が書くべきは、ただのコードではない。「PHPの柔軟性と、Haxeの厳密性を両立させるアーキテクチャそのもの」だ。
さあ、ビルドスクリプトを書き換えろ。次回のレビューで、君のコードにPHPStanが警告を出すことは二度とないはずだ。