WooCommerce 10.9でデュアルAPI登場、PHPコードからGraphQLを自動生成
WooCommerce 10.9で、PHPコードからGraphQL APIを自動生成する「デュアルAPI」が実験的に導入された。AutomatticのRadical Speed Monthイニシアチブの一環として開発されたこの機能は、開発者がPHPクラスに属性（アトリビュート）を付与するだけで、REST APIとGraphQL APIの両方を提供できるようにするものだ。
本記事では、デュアルAPIの技術的な仕組みと、プラグイン開発者にとっての具体的なメリット、現時点での制限と注意点を詳しく解説する。PHP 8.1以上が必須となるため、サーバー環境のバージョンアップを検討している運営者にも役立つ情報をまとめた。
WooCommerceデュアルAPIの概要と狙い
デュアルAPIの3つの構成要素
WooCommerce Developer Blogの記事によれば、デュアルAPIは大きく3つのパーツで成り立っている。1つ目は、PHP属性で装飾されたプレーンなPHPクラスで表現される「コードAPI」だ。これはコマンドパターンで実行可能なクラスか、データ転送オブジェクト（DTO）として定義される。2つ目は、そのコードAPIから自動生成される「GraphQL API」。そして3つ目が、開発時にコードからGraphQLパートを生成する「ビルドスクリプト」である。
なぜGraphQL APIを自動生成するのか
従来のWooCommerce REST APIは、決められたエンドポイントから必要なデータを取得する方式だった。一方、GraphQLはクライアントが必要なフィールドだけをリクエストできるため、オーバーフェッチやアンダーフェッチを防げる。モバイルアプリやヘッドレスコマース構成との相性も良い。しかし、APIを二重にメンテナンスする手間は大きい。そこで、PHPコードを信頼できる唯一の情報源（ソースオブトゥルース）とし、GraphQL側を自動生成することで、開発効率と一貫性を両立させる狙いがある。
コードからGraphQLを自動生成する仕組み
PHPクラスに定義した属性や型情報が、GraphQLスキーマのクエリ名、引数、返却型へと自動的にマッピングされる。開発者はPHPコードだけを書けば、対応するGraphQLエンドポイントが手に入る仕組みだ。
PHP属性によるメタデータの付与
この仕組みの中核が、PHP 8.0で導入された「属性（アトリビュート）」だ。クラスやメソッド、プロパティに #[Name('coupon')] や #[Description('...')] といった形でメタデータを埋め込める。このメタデータをビルドスクリプトが読み取り、GraphQLの型定義やドキュメントを自動構築する。PHPのコードベースがそのままAPIの仕様書になるわけだ。
コマンドクラスとDTOの変換ルール
実行可能なコマンドクラスはGraphQLのクエリやミューテーションに変換される。引数には #[Description] 属性付きで説明がつき、デフォルト値やnull許容もスキーマに反映される。DTOはGraphQLのインプットタイプやアウトプットタイプになる。PHPの列挙型（enum）や #[ArrayOf('int')] のようなカスタム属性を使えば、スカラー型の配列や独自型も正確に表現できる。
ビルドスクリプトの役割
ビルドスクリプトは開発時に一度だけ実行する。WooCommerceコアに同梱されており、プラグイン開発者も自分のコードに対して実行可能だ。スクリプトがコードAPIを解析し、GraphQLスキーマをファイルとして出力する。実行時にはそのスキーマに従ってリクエストが処理されるため、本番環境で毎回コードを解析する必要はない。
プラグイン開発におけるデュアルAPIの活用方法
独自のデュアルAPIを作成する手順
WooCommerce Developer Blogの記事では、プラグイン開発者がこのインフラを再利用して独自のデュアルAPIを構築できる点が強調されている。手順はシンプルだ。まず、プラグイン内にコマンドクラスとDTOを定義し、必要な属性を付与する。次に、WooCommerceのビルドスクリプトを開発時に走らせると、GraphQLパートが自動生成される。最後に rest_api_init フックを使い、ユーティリティメソッドで任意のエンドポイントURLにGraphQL APIを登録すれば完了する。
認証・認可のカスタマイズと拡張ポイント
コアのインフラは、クラスリゾルバ（デフォルトではWooCommerceのDIコンテナ）や、認証用のプリンシパルクラス、認可用の #[RequiredCapability] 属性を提供している。これらはそのまま使うことも、独自の認証・認可ロジックに置き換えることも可能だ。例えば、外部サービスと連携するプラグインであれば、カスタムのプリンシパルクラスを差し込んでAPIキー認証を実装できる。柔軟な拡張性が意識された設計である。
現時点での制限と実験的機能の注意点
後方互換性の保証がない理由
このデュアルAPIは実験的な機能であり、明示的に有効化しない限り動作しない。WooCommerce Developer Blogの記事でも、インフラ部分とコアAPIのいずれについても、将来のリリースで後方互換性のない変更が加えられる可能性があると明言されている。特に、より徹底したテストの過程で、属性の命名規則やクラス構成に破壊的変更が入るかもしれない。本番環境への導入は、安定版となるまで控えたほうが無難だ。
コアAPIのプルーフオブコンセプト
WooCommerce 10.9に同梱されるコアAPIは、製品とクーポンをカバーする限定的なものだ。記事では、これはあくまで「プルーフオブコンセプト（概念実証）」であり、今後のバージョンでクラスやクエリが大幅に変更されるか、まったく別のものに置き換わる可能性があるとされている。現時点では、開発環境やステージング環境でのテスト利用が推奨される。
PHP 7環境の安全性とバージョンアップの必要性
PHP 8.1依存の技術的理由
デュアルAPIはPHP 8.1以上を要求する。これは、PHP属性と列挙型（enum）に依存しているためだ。属性がなければGraphQLスキーマを自動生成できず、enumがなければDTOの厳密な型表現が難しくなる。WooCommerceとしても、公式にPHP 8.1以上を推奨しており、PHP 7.4や8.0のサポートは将来的に終了する方針が示されている。
PHP 7環境での影響と注意点
WooCommerce Developer Blogの記事によると、PHP 8.1固有のコードは、この機能が無効の場合やサーバーがPHP 7.4／8.0で動作している場合には一切実行されない設計になっている。したがって、機能を誤って有効化しようとしてもエラーは発生せず、GraphQLエンドポイントが機能しないだけだ。ただし、プラグインやカスタムコードから src/Api 配下のクラスを直接呼び出すと、PHP 7環境ではエラーになるため注意が必要である。
将来のPHPバージョンサポート計画
WooCommerceは過去にPHP 7.2／7.3のサポートを段階的に終了してきた。今回のデュアルAPI導入は、PHP 8.1移行を加速させる呼び水となるだろう。WordPress 7.0がPHP 7.2／7.3のサポートを打ち切り、PHP 8互換がベータを脱したことも追い風だ。ECサイト運営者は、セキュリティ面とパフォーマンス面からも、早めのPHPバージョンアップを検討すべき局面を迎えている。
この記事のポイント
- WooCommerce 10.9で実験的デュアルAPIが導入され、PHPコードからGraphQL APIを自動生成できるようになった
- PHP属性とDTOによってコードがAPI仕様を兼ね、プラグイン開発者も独自のデュアルAPIを構築可能
- 現時点では後方互換性が保証されない実験的機能であり、本番利用は避け、テスト環境での検証が推奨される
- PHP 8.1以上が必須で、PHP 7環境では機能が無効化されるが、安全面でのリスクは低い
- PHPバージョンアップの必要性が高まっており、ECサイトの将来的な安定稼働に向けて計画的な移行が望ましい
・ 複数業界における17年間のデジタルビジネス開発経験
・ ウェブサイト開発のためのHTML、PHP、CSS、Java等の実用的知識
・ 15ヶ国語対応の多言語SaaSの開発経験
・ 17年間にも及ぶ、Eコマース長期運営経験
・ 幅広い業界でのSEO最適化の豊富な経験