Haxe PHPターゲットの真髄：Composer PSR-4と美しく共存する「名前空間」の最適化術
HaxeをPHPターゲットで利用する際、多くの開発者が陥る罠がある。それは「生成されたコードを、いかに既存のPHPエコシステム（Composer）とシームレスに調和させるか」という点だ。
Haxeの強力なコンパイル時メタプログラミングを活かしつつ、PSR-4に準拠したモダンなPHPプロジェクトに組み込む。これは単なる「設定」の問題ではなく、コンパイラの出力構造を物理レイヤーで支配するという、アーキテクトとしての矜持が問われる領域だ。
今日は、場当たり的な修正ではなく、生産性と保守性を極限まで高めるための「Haxe-PHP-Composer統合パターン」を授ける。
—
1. なぜ「デフォルトのHaxe出力」では不十分なのか
HaxeのPHPターゲットは、デフォルトでは `lib/` ディレクトリにフラット、あるいはHaxeのパッケージ構造をそのまま反映した形で出力される。しかし、これをComposerのオートローダーで読み込ませようとすると、多くの場合、名前空間の衝突やパス解決の不整合が発生する。
特に、大規模プロジェクトにおいて「外部ライブラリ」としてHaxeコードを配置する場合、以下の戦略が必須となる。
1. 名前空間の完全制御: `haxe.root` などの冗長な名前空間を回避する。
2. PSR-4への完全準拠: Composerの `autoload` 設定と出力先ディレクトリの物理階層を一致させる。
—
2. 実践：PSR-4適合のためのビルド設定（hxml）
まずは `build.hxml` を見直そう。ここで重要なのは `-cp` と `-D php-prefix` の使い方だ。
ソースディレクトリ
-cp src
PHP出力ディレクトリ
-php build/php
重要: 名前空間の衝突を防ぐためのプレフィックス指定
これにより、Haxeのクラスは \MyProject\Generated\… に配置される
-D php-prefix=MyProject\\Generated
以下のフラグはPHPターゲットにおけるパフォーマンスと互換性の要
-D php-std-lib-path=../vendor/haxe/php-stdlib # 任意: 標準ライブラリを分離
-dce full # デッドコード除去（Dead Code Elimination）は必須。プロダクションのバイナリを劇的に軽量化する
なぜ `php-prefix` を使うのか？
PHPの世界では、サードパーティライブラリとの名前空間の競合は致命的なバグの温床となる。`php-prefix` を指定することで、Haxeが生成する全てのクラスに一意のルート名前空間を強制できる。これにより、`Composer` のオートローダーが生成するマッピングと物理的に直交する設計が可能になる。
—
3. Composerと統合するための `composer.json` 設定
Haxeが生成したコードを、PHP側からは「ただのクラス」として呼び出せるようにする。
{
“autoload”: {
“psr-4”: {
“MyProject\\Generated\\”: “build/php/”
}
}
}
これで、Haxe側で `package domain.user;` として作成したクラスは、PHP側で `use MyProject\Generated\domain\user\User;` として完全に透明な形で呼び出せるようになる。
—
4. プロダクションで生き残るための「抽象型」活用例
PHPへのトランスパイルにおいて、パフォーマンスを損なわず、かつ安全に型を扱うには「抽象型（Abstract Types）」が最強の武器となる。特に、外部のPHP APIと連携する際、`dynamic` を使うのは素人のやり方だ。
package domain;
// PHPの連想配列を型安全にラップする例
abstract UserData(php.NativeAssocArray
public var id(get, never):Int;
inline function get_id():Int return this[‘id’];
@:to
public function toString():String return ‘User:${this[‘name’]}’;
}
このように抽象型を定義しておくことで、PHPの柔軟なデータ構造を保ちつつ、Haxeの静的型チェックの恩恵をコンパイル時に享受できる。実行時のオーバーヘッドはゼロ（inline）であり、この抽象化こそがHaxeがPHPターゲットとして選ばれる理由だ。
—
5. 最後に：アーキテクトからの助言
HaxeとPHPを組み合わせる際、最も恐れるべきは「Haxeが生成したコードをPHP側で無理やり修正すること」だ。
- ルール: 生成されたコードには決して手を触れないこと。
- 解決策: 挙動を変えたい場合は、Haxe側のコードを変更し、再ビルドする。それが難しい場合は、Haxeの `extern` クラスを定義し、PHP側の既存コードをラップする設計へ移行せよ。
コンパイラは忠実な奴隷だ。我々が正しい定義（型とアーキテクチャ）を与えれば、それ以上の精度でコードを生成してくれる。HaxeのビルドプロセスをCI/CDパイプラインの深部に組み込み、`composer dump-autoload` と同期させる。このフローを確立したとき、君のプロジェクトは真に堅牢なものとなる。
迷わず書け。コンパイラが君の味方である限り、ランタイムのエラーは大幅に削減されるはずだ。