HaxeとPHPの「境界線」を消し去る：PSR-4オートローダー完全同期術
HaxeをPHPターゲットで使う際、多くの人が最初にぶつかる壁が「なぜかクラスが見つからない」「名前空間が噛み合わない」というエラーですよね。
Haxeは強力な型システムを持つ言語ですが、PHPの柔軟すぎる（あるいは複雑な）オートローダーとは、時に相性が悪いように見えます。しかし、本質さえ掴めば、Haxeの型安全性とComposerの広大なライブラリ資産を完璧に融合させることは可能です。
今日は、Haxeのパッケージ階層をPSR-4と同期させ、開発時の「読み込みエラー」を根絶する極限の構成術を伝授します。
—
1. そもそも、なぜ「名前空間」の衝突が起きるのか
Haxeのパッケージは、そのままディレクトリ構造になります。一方、PHPのComposer（PSR-4）は、「この名前空間は、このディレクトリに対応する」というマッピングを`composer.json`で定義します。
問題の根本：
Haxeが生成するPHPファイル群のパスと、Composerが期待するパスが微妙にズレると、PHPエンジンは「ファイルはあるのに、クラスがロードできない」という迷子状態に陥ります。
—
2. 極限の構成術：ディレクトリとマッピングの最適化
以下のディレクトリ構成を標準としてください。これが最もトラブルが少ない「黄金の構成」です。
/project-root
├── composer.json # PHPの依存管理
├── build.hxml # Haxeのコンパイル設定
├── src/ # Haxeのソースコード (com.myapp…)
└── bin/ # Haxeの出力先 (PHPコード)
composer.json の設定
ここで重要なのは、`autoload`セクションでHaxeの出力先を認識させることです。
{
“autoload”: {
“psr-4”: {
“App\\”: “bin/”
}
}
}
※ポイント：Haxeが生成するPHPファイルのルートを`bin/`として定義します。
—
3. Haxe側の設定（build.hxml）
Haxeから生成されるPHPコードを、Composerが読み取れる形にするのがコツです。`–php-lib`オプションとパッケージ指定を組み合わせます。
build.hxml
-cp src
-main Main
-php bin
ここが重要！生成されるPHPの名前空間をComposerと一致させる
-D php-prefix=App
解説：
`-D php-prefix=App` を指定することで、Haxeが生成する全クラスに `App\` という名前空間が付与されます。これで、ComposerのPSR-4マッピングとHaxeのパッケージが完全に同期します。
—
4. 既存ライブラリを「Haxe流」に呼び出す（externの極意）
Composerで入れたライブラリをHaxeから使うには、`extern`クラスを定義します。これがHaxeが「型を掌握する」ための儀式です。
例えば、`Monolog`を使いたい場合：
// src/vendor/Monolog.hx
package vendor;
// @:phpGlobal を使って、Composerでインストールしたクラスへ直結する
@:native(“Monolog\\Logger”)
extern class Logger {
public function new(name:String):Void;
public function info(message:String):Void;
}
ここで注意！
`@:native`で指定する名前空間は、PHP側から見た名前空間です。ここを間違えると実行時に「Class not found」で即死します。
—
5. 初学者が陥りやすい罠と解決策
- 罠1：`composer dump-autoload` を忘れる
Haxeでコードを生成した直後、Composerは新しいファイル構造を認識していません。必ずコンパイル後にコマンドを叩いてください。
haxe build.hxml
composer dump-autoload
- 罠2：パッケージ名の大文字・小文字問題
Linux環境では大文字・小文字は厳密です。Haxeのパッケージ `com.example` は必ず `com/example/` ディレクトリと一致させてください。
—
魂のまとめ
HaxeからPHPを扱う際、「Haxeは単なるPHP生成機ではない。型という秩序をもたらすアーキテクトである」と意識してください。
1. `composer.json` でPSR-4ルートを `bin/` に固定する。
2. `build.hxml` で `-D php-prefix` を指定し、名前空間を揃える。
3. 外部ライブラリは `extern` で型付けし、`@:native` で橋渡しする。
この3ステップをマスターすれば、もうファイル読み込みエラーに怯える必要はありません。Haxeの強力なコンパイル時チェックと、PHPの広大なエコシステムが、あなたの手の中でひとつに繋がります。
ここをクリアすれば、Haxeの基本はバッチリマスターできたも同然です。さあ、次はどんな巨大なシステムを構築しましょうか？応援していますよ！