こんにちは！Haxeの世界へようこそ。
今回は、Haxeの強力なクロスプラットフォーム機能の一つである「PHPターゲット」を取り上げます。
「Haxeから既存のPHPライブラリやComposerパッケージをスマートに呼び出したい！」
「でも、Haxeのパッケージ階層とPHPのPSR-4名前空間がごちゃ混ぜになって、コンパイルエラーやオートロードの迷子になってしまう……」
そんな悩みを持ったことはありませんか？
ここをクリアすれば、HaxeとPHPの連携はあなたの最強の武器になります。今回は、Haxeのパッケージ構造とPHPの名前空間を美しく調和させるための「ディレクトリ戦略の最適解」を、優しく紐解いていきましょう。
—
なぜ名前空間とパッケージ構造で衝突が起きるのか？
Haxeは、すべてのコードを「パッケージ」という概念で整理します。例えば `src/com/example/MyClass.hx` というファイルを作ると、Haxeは自動的に `com.example.MyClass` というクラスを作り出します。
一方、現代のPHPエコシステム（Composerなど）では、PSR-4という規格に基づく名前空間とディレクトリのオートローディングが主流です。
これらを何も考えずに混ぜてしまうと、次のような悲劇が起きます。
- Haxeが生成したPHPコードに名前空間がうまく付与されない
- Composerでインストールした外部ライブラリ（例: `Monolog\Logger` など）をHaxe側から型安全に呼び出せない
この問題を解決するには、「Haxeのソースツリー」と「PHPの出力先、そしてComposerのオートローダー」の三者の関係を正しくデザインする必要があります。
—
黄金のディレクトリ戦略：物理配置の全体像
まずは、プロジェクト全体のディレクトリ構造の最適解を見てみましょう。ここが今回のキモになります。
my-haxe-php-project/
├── composer.json # 外部PHPライブラリの管理
├── build.hxml # Haxeのコンパイル設定
├── src/ # Haxeのソースコード置き場
│ └── app/
│ └── Main.hx # Haxeのエントリーポイント
└── output/ # HaxeがPHPコードを出力する場所（公開ディレクトリなど）
├── index.php # 実行のエントリーポイント
├── vendor/ # Composerの依存関係（自動生成）
└── lib/ # Haxeが生成したPHPコードの出力先
この構成のポイントは、「Haxeが生成するPHPファイル群」と「Composerのベンダー領域」をきれいに住み分けさせつつ、Haxeのマジックで名前空間を完全一致させることです。
—
ステップ1: Haxeのexternを活用してPHPパッケージを迎え撃つ
Haxeから既存のPHPライブラリ（例えば、広く使われているユーティリティやComposerパッケージ）を呼び出すには、extern（外部定義）という機能を使います。これは「中身の実装はPHP側に任せるから、Haxe側にはこういう型があるよとだけ教えてあげる」という、Haxeの神髄とも言える機能です。
例えば、PHP側にある `Vendor\Package\Tool` という名前空間のクラスをHaxeから使いたいとしましょう。
`src/vendor/package/Tool.hx` の作成
package vendor.package;
// @:nativeメタデータを使って、生成されるPHP側の正確な名前空間とクラス名を指定します
@:native(“Vendor\\Package\\Tool”)
extern class Tool {
// コンストラクタの定義
public function new(name:String);
// 外部PHPメソッドのシグネチャを定義
public function run():String;
}
ここがポイント：
Haxeのパッケージ構造（`package vendor.package;`）をPHPの階層に合わせつつ、`@:native` メタデータでバックスラッシュ（`\\`）のエスケープに注意しながら正確なPHPのクラス名をマッピングします。これだけで、Haxeのコンパイラは型安全性を保ったままPHPのコードを生成してくれます。
—
ステップ2: build.hxml の設定を極める
次に、この構成を正しくビルドするための `build.hxml` を見てみましょう。ここでのコンパイルフラグが、PHP連携の成否を握っています。
`build.hxml` の記述例
ソースコードのルートディレクトリを指定
-cp src
エントリーポイントの指定
-main app.Main
PHPターゲットを指定し、出力先を output/lib に設定
-php output/lib
【重要】PHP7/8以降のモダンな機能をフルに活かすためのフラグ
-D php-front=index.php
この設定でコンパイルを行うと、Haxeは `src/` 以下のHaxeコードを綺麗にPHPにトランスパイルし、`output/lib/` 内に配置してくれます。
—
ステップ3: ComposerとHaxe生成コードの統合
最後に、出力されたHaxeのPHPコードと、Composerのオートローダーを結合させます。
出力ディレクトリ（`output/`）の直下に `index.php` を置き、次のように読み込みます。
`output/index.php` の実装例
陥りやすい文法・設定エラーと対策
ここで、初心者がよくハマるポイントをいくつか先回りしてクリアしておきましょう。
1. バックスラッシュのエスケープ忘れ
- `@:native(“MyNamespace\\MyClass”)` のように、Haxeの文字列リテラル内ではバックスラッシュを二重（`\\`）にする必要があります。これを忘れると、生成されるPHP側で名前空間のパースエラーが起きます。
2. 大文字・小文字の不一致
- Haxeのクラス名は通常アッパーキャメルケース（例: `MyClass`）ですが、ファイル名も完全に一致させる必要があります。PHPはOSによっては大文字小文字を厳密に区別するため、ここがズレるとオートロードで `Class not found` のエラーになります。
—
まとめ：ここをクリアすればHaxeの基本はバッチリ！
今回は、Haxeのパッケージ階層とPHPの名前空間を調和させるためのディレクトリ戦略について解説しました。
- `src/` にHaxeのパッケージ構造を綺麗に配置する
- `@:native` を使ってPHPの外部名前空間と正確にブリッジする
- ComposerのオートローダーとHaxeのBootローダーを適切に共存させる
このデザインパターンさえ押さえておけば、既存の膨大なPHP資産やLaravelなどのモダンなComposerパッケージを、Haxeの強烈な型システムとマクロの恩恵を受けながら安全に統帥することができます。
クロスプラットフォーム開発の醍醐味である「異言語間連携」、ぜひあなたのプロジェクトでも試してみてくださいね！