Phpactor Setup for BEAR.Sunday

VS Codeでsuzumaze/bear-phpactor-extensionを使うためのセットアップ拡張です。

BEAR.Sunday固有の定義ジャンプ、参照検索、補完はbear-phpactor-extensionがPhpactor / LSP上で提供します。この拡張は、それらを再実装せず、VS Code向けのインストールと設定だけを担当します。

VS Code
  ↓ Phpactor公式VS Code拡張
Phpactor / LSP
  ↓
bear-phpactor-extension

必要なもの

• VS Code 1.91以上
• PHP 8.2以上
• Composer
• Phpactor公式VS Code拡張

Phpactor公式拡張はextension packとして一緒にインストールされます。無効化されている場合は、拡張画面から有効化してVS Codeを再読み込みしてください。

コマンドの実行方法

1. macOSではShift+Command+P、Windows/LinuxではCtrl+Shift+Pを押してコマンドパレットを開きます。
2. Phpactor Setup for BEAR.Sundayと入力します。
3. 表示されたコマンドを選んで実行します。

このREADMEに記載する拡張コマンドは、すべてこの手順で実行します。ターミナルやPhpactor CLIへ入力するコマンドではありません。

セットアップ

bear/resourceをrequireまたはrequire-devに持つプロジェクトを開くと、未セットアップの場合だけ案内が表示されます。「セットアップする」を選び、完了後にVS Codeを再読み込みしてください。

手動で実行する場合は、コマンドパレットから次を選びます。

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

同じローカルVS Code環境では一度だけ必要です。設定したPhpactorは複数のBEAR.Sundayプロジェクトで共有されます。VS Codeのプロファイル、Insiders、SSH、Dev Containerはそれぞれ別環境です。

コアの確認と更新

現在使用中のbear-phpactor-extensionを確認するには、次を実行します。

Phpactor Setup for BEAR.Sunday: 使用中のコアバージョンを確認

表示された通知の「コアを更新」ボタン、または次のコマンドから、互換範囲内の最新版へ更新できます。

Phpactor Setup for BEAR.Sunday: コアを更新

更新後はVS Codeを再読み込みしてください。この操作が更新するのはbear-phpactor-extensionとその依存パッケージだけです。Phpactor本体、phpactor.path、Phpactorのグローバル設定は変更しません。

現在の対応範囲は^0.1.3です。0.1.xはセットアップ拡張を入れ直さず更新できます。互換範囲を越えるリリースには、対応版のセットアップ拡張が必要です。

TwigとQiq

BEAR.SundayのHTMLマニュアルでは、HTMLテンプレートエンジンとしてQiqとTwigが案内されています。

Qiqテンプレートは.phpファイルなので、通常どおりPhpactorへ送信されます。

Phpactor公式VS Codeクライアントは、Twig文書を標準ではLanguage Serverへ送りません。BEAR標準配置の.html.twigを試す場合は、プロジェクトの.vscode/settings.jsonへ次を追加します。

{
    "files.associations": {
        "*.html.twig": "php"
    }
}

これはTwigをPHP文書として送る暫定策です。言語モードがPHPになるため、Twigのsyntax highlight、診断、formatter、他のTwig拡張へ影響する場合があります。不都合があれば設定を削除してください。

.html.twigはTwig必須の拡張子ではなく、BEAR.Sunday TwigModuleの標準配置に合わせた指定です。対応するジャンプ構文はbear-phpactor-extensionのREADMEを参照してください。

変更する場所

対象プロジェクトのcomposer.jsonや.vscode/settings.jsonは変更しません。Phpactorとコアは、この拡張のglobalStorageUri配下へインストールします。

グローバルに変更するのは次の2点です。

• $XDG_CONFIG_HOME/phpactor/phpactor.json（通常は~/.config/phpactor/phpactor.json）
• VS Code User Settingsのphpactor.path

既存のPhpactor設定は保持し、BEAR.Sunday拡張クラスだけを追加します。不正なJSON、symlink、通常ファイルでない設定、処理中の同時変更を検出した場合は、上書きせず中止します。

クリーンアンインストール

この拡張が管理するPhpactorとbear-phpactor-extensionを削除し、Phpactorのグローバル設定とphpactor.pathを初回セットアップ前の状態へ戻すには、コマンドパレットから次を実行します。

Phpactor Setup for BEAR.Sunday: クリーンアンインストール

実行前に削除内容を確認します。現在値がセットアップ時の値と一致する場合だけ自動復元し、セットアップ後のユーザー変更を検出した場合は、破棄してよいか別途確認します。確認後に値が変わった場合も上書きしません。

この操作は、このセットアップ拡張自体やPhpactor公式VS Code拡張をアンインストールしません。不要であれば、クリーンアンインストールの完了後にVS Codeの拡張画面から削除してください。VS Code拡張のアンインストールを契機とした自動削除は行いません。

バージョン方針

管理対象Composer環境は、動作確認した組み合わせを固定します。

Phpactorは内部extension APIの互換性を常に保証するわけではないため、未検証の最新版へ自動追従しません。通常の再セットアップはcomposer.lockを再現し、「コアを更新」を実行した場合だけコアを互換範囲内で更新します。

phpactor/language-server-protocolは、未保存変更のtextDocument/didChangeに関する既知の組み合わせを避けるため3.17.4へ固定しています。修正済みstable releaseとPhpactorの互換性を確認後に更新します。関連: phpactor/language-server#68

Phpactorはプロジェクトdependencyとしてではなく、この拡張専用の領域へインストールします。これはPhpactor公式のインストール方針に沿ったものです。

既知の制約

• phpactor.pathはUser Settingsへ書くため、BEAR.Sunday以外のワークスペースにも影響します。
• WorkspaceまたはWorkspace Folderに別のphpactor.pathがあれば、VS Codeの優先順位でそちらが使われます。
• Phpactor公式拡張が無効な場合、この拡張から有効化することはできません。
• セットアップ後にXDG_CONFIG_HOMEを変えた場合は、元の環境でクリーンアンインストールしてから再セットアップしてください。
• 現在の実機確認はmacOSのみです。Linuxは未確認です。WindowsではPhpactor公式クライアントがWSLまたはLinux VMを案内しています。
• Twigの制約は「TwigとQiq」のとおりです。

関連プロジェクト

• bear-phpactor-extension: BEAR.Sunday固有のPhpactor/LSP機能
• BEAR.Sunday Extension Pack: VS Code APIで実装された先行プロジェクト
• idea-php-bearsunday-plugin: PhpStorm向けプラグイン

本プロジェクトは先行プロジェクトを置き換えるものではありません。BEAR.Sunday固有の意味をLanguage Server側へ置き、複数のLSPクライアントから利用する別の構成です。