Phpactor Setup for BEAR.Sunday

BEAR.Sunday固有のIDE/LSP機能を提供するComposerパッケージ suzumaze/bear-phpactor-extensionを、 VS CodeのPhpactorから利用できるようにするセットアップ専用の薄い拡張機能です。

目的と責務

この拡張自身はResource URI解析、SQL・ALPS・JSON Schema・Routerの解決、定義ジャンプ、参照検索、補完などを実装しません。BEAR.Sunday固有の知識はbear-phpactor-extensionに置き、本拡張はVS Code固有のインストールと設定だけを担当します。

BEAR.Sunday固有のIDE/LSP機能
        ↓
bear-phpactor-extension
        ↓
Phpactor / LSP
        ↓
VS Code / Neovim / Emacs / その他LSP client

VS Code固有のセットアップ
        ↓
phpactor-setup-for-bear-sunday

対象プロジェクトのcomposer.jsonや.vscode/settings.jsonは変更しません。Phpactorとbear-phpactor-extensionは本拡張のglobalStorageUri配下へインストールし、次の2点だけをglobalに反映します。

• $XDG_CONFIG_HOME/phpactor/phpactor.json（未設定時は~/.config/phpactor/phpactor.json）
• VS Code User Settingsのphpactor.path

これは1つのworkspace専用設定ではありません。複数のBEAR.Sundayプロジェクトから、同じ管理対象Phpactor installationを共有する設計です。

要件

• PHP 8.2以上
• Composer
• VS Code 1.91以上（依存するphpactor.vscode-phpactor 1.7.8と同じminimum）

PHPはComposer実行前にPHP_VERSION_IDで検査し、8.2未満なら環境を変更せず終了します。

使い方

bear/resourceをrequireまたはrequire-devに持つプロジェクトを開くと、グローバルセットアップであることを明記した確認通知が表示されます。コマンドパレットから手動実行することもできます。

Phpactor Setup for BEAR.Sunday: グローバルセットアップ

setup後にPhpactorを元の状態へ戻す場合は、次を実行します。

Phpactor Setup for BEAR.Sunday: グローバルセットアップを元に戻す

非破壊setupとrestore

初回setupでは、ユーザー環境へ書き込む前に次の状態をExtensionContext.globalStateへ保存します。再setupでこのoriginal backupを現在値に置き換えることはありません。

• global Phpactor configが存在したか、および存在した場合の元の内容
• VS Code User Settingsとして明示されていたphpactor.path（inspect('path').globalValue）
• phpactor.pathが未設定だったこと
• 本拡張が書いたconfigの内容とSHA-256
• 本拡張が設定したPhpactor pathと管理対象install directory
• state schema versionとsetup extension version

既存global configは丸ごと置き換えません。setupは次の順序で処理します。

1. 既存configをJSON objectとして検証する。invalid JSON、symlink、通常ファイルでない場合は変更せず中止する。
2. 既存config全体を作業用.phpactor.jsonのseedにする。
3. bear-phpactor-initへcontainer.extension_classesの再生成と重複除去を任せる。
4. 生成結果が既存の他キーと既存extension classをすべて保持し、BEAR extension classを先頭に1回だけ含むことを検証する。既存classが生成結果から消えた場合は、別のComposer autoloaderが必要な可能性があるため、独自mergeせずsetupを中止する。
5. setup中の同時変更がないことを再確認し、一時ファイルをflushしてrenameするatomic writeでglobal configへ反映する。

したがって、PHPStan、PHP CS Fixer、indexer、completion等の既存設定は保持されます。既存configが壊れている場合に、勝手な修正・削除・上書きは行いません。

restoreは現在値と「setup時に本拡張が書いた値」を比較します。一致するときだけ自動復元し、元々configがなければ生成ファイルを削除、元々phpactor.pathが未設定ならUser setting自体を未設定へ戻します。本拡張の管理対象install directoryも削除します。

setup後のユーザー変更を検出した場合は、変更対象を明示したmodal warningを出します。defaultはCancelで、ユーザーが「変更を破棄して復元」を明示的に選んだ場合だけoriginal backupを上書きします。確認時と書き込み直前のsnapshotが異なる場合は、確認後の変更を上書きせず中止します。途中まで復元して失敗した場合も項目ごとに進捗を保存するため、restoreは再実行可能で冪等です。

Phpactor互換性方針

この拡張が生成するComposer projectは、phpactor/phpactorを2026.07.22.0へexact pinします。これはbear-phpactor-extension v0.1.0の開発・テスト環境で使われ、Phpactor公式VS Code client 1.7.8も取得しているreleaseです。

Phpactorのversionはリリース日を表すCalVer形式です。日付が新しいことは、内部extension class構成やextension APIとの互換性を保証しません。bear-phpactor-extensionはその内部構成に依存するため、未検証の将来versionを*やlatestで自動取得せず、検証後にpinを意図的に更新します。

初回解決後のcomposer.lockは管理対象install directoryに保持します。通常の再setupはcomposer installで同じdependency graphを再現し、この拡張がcompatibility manifestを意図的に変更したときだけcomposer updateで再解決します。

phpactor/language-server-protocolは3.17.4のexact pinを維持します。language-server 7.0.1とprotocol 3.17.5以上の組合せには、未保存変更のtextDocument/didChangeが届かない既知regressionがあります。修正PR phpactor/language-server#68は2025-12-29にmerge済みですが、2026-09-04時点の最新stable tagは修正を含まない7.0.1です。修正版stable releaseへの収録と、pinしたPhpactorとの互換性を確認できるまで解除しません。

Composerのminimum-stability: devも維持します。Phpactor 2026.07.22.0自身がjetbrains/phpstorm-stubs: dev-masterとphpactor/tolerant-php-parser: dev-phan-phactor-fixesをrequireするためです。一方、実際の一時Composer環境で解決できることを確認した上でprefer-stable: trueとし、それ以外はstable packageを優先します。

正直な開示

Phpactorの公式READMEには次のように明記されています。

Phpactor is a general tool, it is not intended that it be installed as a project dependency.

本拡張はこの方針に沿い、対象プロジェクトのdependencyには追加しません。ただし、Phpactorのboot時にcontainer.extension_classesの全classが同じComposer autoloaderから読める必要があるため、本拡張専用のglobal storage内でPhpactorとbear-phpactor-extensionを一緒に管理します。

Prior Art（先行プロジェクト）

BEAR.Sunday向けのVS Code支援には、Yuki Adachi氏によるBEAR.Sunday Extension Packという先行プロジェクトがあります。同Extension PackはResource、SQL、Aura Router、Twigなど、BEAR.Sunday開発で必要とされたnavigation機能をVS Code拡張として提供しており、本プロジェクトにとって重要なprior artです。

本プロジェクトはそれを置き換えるものではありません。先行方式にはinstallが単純でdependencyが少なく、VS Codeだけを対象とする場合に直接的という利点があります。本プロジェクトは、現在のPhpactor/LSP extension architectureを使い、framework固有の知識をLanguage Server側へ集約する別の構成です。definitionに加えてcompletion、references、type definition等へ展開しやすく、NeovimやEmacsを含む他のLSP clientからも利用できます。

なお、bear-phpactor-extension v0.1.0はTwig navigationを実装していません。先行Extension Packの機能をすべて包含しているとは位置づけず、Twigは既存のTwig toolingとの役割分担を今後検討する対象です。

IDEA（PhpStorm）

同じ問題領域には、より機能が多く活発に開発されているidea-php-bearsunday-pluginがあります。PhpStormではそちらを利用してください。

既知の制約

• global setupなので、User Settingsのphpactor.pathはBEAR.Sunday以外のworkspaceにも影響します。
• global Phpactor configへBEAR extension classを登録するため、別のPhpactor installationが同じconfigを読む場合は、そのComposer autoloaderからclassを読み込めるか注意が必要です。既存extension classを管理対象installationで再生成できない場合、本拡張は黙って削除せずsetupを中止します。
• WorkspaceまたはWorkspace Folderに別のphpactor.pathがある場合はVS Codeの優先順位でそちらが勝ちます。本拡張はUser settingだけを保存・復元し、workspace設定は変更しません。
• setup済みの状態でXDG_CONFIG_HOMEを変えると、誤った場所へbackupを復元しないよう再setupを中止します。元の環境でrestoreしてからやり直してください。
• backup機能導入前の旧版ですでにsetup済みの場合、旧版が介入する前の状態は遡って復元できません。初回更新時に警告し、その時点のconfigとUser settingを復元基準として保存します。
• setup後のconfigをsemantic mergeで巻き戻すことはしません。後編集があれば自動restoreを止め、明示確認を求めます。
• uninstall時の自動restoreは行いません。拡張を削除する前にrestore commandを実行してください。
• global install方式は現在macOSの1環境でのみ実機確認済みです。Linuxは未確認で、WindowsではPhpactor公式clientがWSLまたはLinux VMの利用を案内しています。
• Twig navigationは提供しません。

サポート体制

個人の趣味プロジェクトであり、ベストエフォートでのサポートです。issueやpull requestは歓迎しますが、対応の保証はありません。Phpactor upstreamの内部構成変更により、pin更新には追加検証が必要になる場合があります。