feat: EC-CUBE 4.4 (Symfony 7.4 / Doctrine ORM 3.0 / PHP 8.2 以上) 対応

[nanasess]

概要

決済プラグイン実装サンプル (SamplePayment) を EC-CUBE 4.4 (Symfony 7.4 / Doctrine ORM 3.0 / PHP 8.2 以上) へ対応しました。
あわせて、本対応で得た手順を他の決済プラグインへ展開できるモデルケースとして整理しています。

プラグインコードは EC-CUBE のバージョンに合わせ SamplePayment42 → SamplePayment44、パッケージ名は ec-cube/samplepayment42 → ec-cube/samplepayment44 (version 3.0.0) に変更しました。

移行手順 (他の決済プラグイン向けモデルケース)

1. 動作環境を 4.4 へ

• docker-compose.yml の image を ${TAG} でパラメータ化し、デフォルトを 8.2-apache-4.4 に。
• 落とし穴: dev の entrypoint は起動時に eccube:plugin:enable を自動実行する。未移行コード (アノテーション/戻り型なし) は Symfony 7.4/PHP 8.2 で読めず Compile Error になりコンテナが healthy になる前に exit する。up -d --wait は移行完了後の検証ステップであり、最初には通らない。

2. 静的解析・整形ツールの導入 (Resource/ 配下に置く)

• rector / php-cs-fixer / phpstan の設定はプラグインのルート直下に置かない。本体の Plugin\: サービス検出に巻き込まれ Plugin\<Code>\rector クラスを期待されて 500 になるため、exclude 対象の Resource/ 配下に置く。
• 本体イメージは vendor/ を焼き込んでいないため、初回 rector は「プラグインを有効化しない一回限りコンテナ」で docker-php-entrypoint により vendor を展開してから実行する。

3. rector による自動変換 (アノテーション → アトリビュート)

• @Route → #[Route]、@ORM\* → #[ORM\*] + 型付きプロパティ、constructor promotion が自動変換される。

4. rector で変換しきれない手動対応 (山場)

• @EntityExtension → #[EntityExtension(...)] (本体の名前空間・記法変更, rector 非対象)。
• @Template → #[Template(...)] (Symfony\Bridge\Twig\Attribute\Template)。Sensio FrameworkExtraBundle が 4.4 に無いため手動。
• Entity trait のゲッターを nullable 化 (PHP 8.2 の厳格な戻り型。未設定時 500 を防ぐ)。
• PaymentMethodInterface の戻り型変更 (決済プラグイン特有・最重要):
  • verify(): PaymentResult|bool — 成功時は false を返す (成功時に PaymentResult を返すと本体で getResponse()->isRedirection() が null 呼び出しになり 500)。
  • apply(): PaymentDispatcher|bool — リダイレクト不要時は false。
• buildForm() / configureOptions() / enable() / getSubscribedEvents() 等に戻り型を追加。
• constructor promotion で DI bind 引数名を保持 ($shoppingPurchaseFlow 等は rector が引数名をプロパティ名へ改名するため、promotion 前にプロパティ名を bind 名へ揃える)。

5. E2E テスト (Playwright) の調整

• 4.4 ではカート追加が AJAX 化し /cart へ自動遷移しないため、AJAX 完了を待って明示的に遷移。
• SQLite + 並列実行は競合するためローカルは --workers=1。

このプラグインでの変更点

• feat: EC-CUBE 4.4 (Symfony 7.4 / Doctrine ORM 3.0 / PHP 8.2) 対応
• refactor!: プラグインコードを SamplePayment42 → SamplePayment44 へ改名 (BREAKING: パッケージ名・コード変更、要再インストール。DB スキーマは snake_case のため不変)
• fix: テンプレートの version-less 名前空間 (Plugin\SamplePayment\...) を SamplePayment44 へ修正 (受注編集画面の Twig RuntimeError)
• test: 受注編集画面・決済金額変更のリグレッション E2E を追加
• ci: Playwright workflow を 4.4 / PHP 8.2-8.5 の matrix へ更新 (npm ci → yarn、actions を v4 へ)
• docs: README のコード例を Symfony 7 / 4.4 へ更新、ファイル概要の旧クラス名・リンクを修正
• feat: 決済金額変更に bcmath (bcadd/bcsub/bcmul/bcdiv) の加減乗除サンプルを追加 (拡張が無くても nanasess/bcmath-polyfill 経由で動作)

テスト

• rector --dry-run 差分ゼロ / php-cs-fixer 準拠
• cache:clear 後にコンテナが healthy、[OK] Plugin Enabled.
• PHP 8.2 / 8.5 の実イメージで起動・E2E パスを確認 (matrix の両端)
• E2E 5 件パス (guest_convini / guest_credit_link / guest_credit_token / 受注編集 constant() 回帰 / changePrice bcmath)
• 未移行コード (4.3) は 4.4 イメージで起動失敗することを実機で確認 (移行の必要性の裏取り)