PhpactorをLSPサーバーとして活用する方法 -- 導入からエディタ設定・性能改善まで

PHP開発でコード補完や定義ジャンプを実現するには、エディタとLanguage Server（言語サーバー）の連携が不可欠です。Phpactorは、PHP自体で実装されたオープンソースのLSPサーバーであり、MIT ライセンスのもと無料で全機能を利用できます。Neovim、VSCode、Emacs、Helix、Zedなど主要エディタの大半に対応しており、PHP 8.1以上の環境で動作します。

この記事では、Phpactorが備えるLSP機能の全容、各エディタでのセットアップ手順、設定ファイルの書き方、大規模コードベースでの速度改善策、そしてIntelephenseとの機能的な違いを整理します。

LSPとPhpactorの位置づけ

Language Server Protocol（LSP）は、エディタ（クライアント）と言語サーバーがJSON-RPCで通信する標準プロトコルです。Microsoftが策定し、現在は多くの言語・エディタが採用しています。PHP向けのLSPサーバーとしては、商用のIntelephenseとオープンソースのPhpactorが二大選択肢です。

Phpactorの開発は Daniel Leech 氏（GitHub: dantleech）を中心に進められており、GitHub上では1,800以上のスターと100名超のコントリビューターを擁しています。リポジトリは phpactor/phpactor で公開されています。2025年12月リリースのバージョン 2025.12.21.1 が最新安定版です（2026年1月10日公開）。

Phpactorが対応するLSP機能

Phpactorは多くのLSPメソッドを実装しています。以下に対応状況をまとめます。

対応済み機能

機能カテゴリ	対応内容
コード補完	クラス名・メソッド・プロパティの補完、use文の自動挿入
ホバー情報	カーソル位置のシンボルに関する型情報・ドキュメント表示
シグネチャヘルプ	関数・メソッド呼び出し時の引数ヒント
定義ジャンプ	Goto Declaration / Goto Type / Goto Implementation
参照検索	クラス・関数・メンバーアクセス（静的・インスタンス）の参照一覧
ドキュメントハイライト	同一シンボルの出現箇所をハイライト
ワークスペースシンボル	クラス・関数・定数のプロジェクト横断検索
ドキュメントシンボル	現在のファイル内のシンボル一覧
選択範囲	Selection Range によるスマートな範囲選択
コードアクション	クイックフィックス・リファクタリング操作
フォーマット	php-cs-fixer 連携によるコード整形
リネーム	変数・メンバーの名前変更（クラス名・名前空間のリネームは今後対応予定）
診断	PHP構文チェック + PHPStan / Psalm / php-cs-fixer 連携

未対応の機能

Code Lens、Document Link、Document Color、Color Presentation、Range Formatting、Folding Range は現時点で未実装です。

インストール手順

Phpactorは複数の方法で導入できます。PHP 8.1以上と mbstring 拡張が前提条件です。

PHAR ファイル（推奨）

もっとも手軽な方法です。GitHub Releases からビルド済みバイナリをダウンロードします。

curl -Lo phpactor.phar https://github.com/phpactor/phpactor/releases/latest/download/phpactor.phar
chmod a+x phpactor.phar
mv phpactor.phar ~/.local/bin/phpactor

Git Clone + Composer

最新の開発版を利用したい場合や、ソースコードを直接参照したい場合に適しています。

git clone https://github.com/phpactor/phpactor.git
cd phpactor
composer install

bin/phpactor が実行可能ファイルになります。PATHの通った場所にシンボリックリンクを作成してください。

ln -s "$(pwd)/bin/phpactor" ~/.local/bin/phpactor

パッケージマネージャ経由

Arch Linux（AUR）: yay -S phpactor
NixOS / Nix: nix-shell -p phpactor

動作確認

インストール後、以下のコマンドで環境が正しいか検証できます。

phpactor status

PHP バージョン、拡張モジュール、設定ファイルの読み込み状況が表示されます。

エディタ別セットアップ

Neovim（0.11以降ネイティブLSP）

Neovim 0.11.0 以降では、プラグインなしでLSPクライアントを利用できます。以下の2ファイルを作成するだけで動作します。

~/.config/nvim/lsp/phpactor.lua:

return {
  cmd = { 'phpactor', 'language-server' },
  filetypes = { 'php' },
  root_markers = { 'composer.json', '.git', '.phpactor.json', '.phpactor.yml' },
}

~/.config/nvim/init.lua に追加:

vim.lsp.enable('phpactor')

補完時のドルマーク問題への対処

PHPの変数名は $ で始まりますが、補完候補にも $ が含まれるため二重入力になるケースがあります。Phpactorの設定で先頭のドルマークを除去できます。

{
  "language_server_completion.trim_leading_dollar": true
}

あるいは Neovim 側で iskeyword に $ を追加する方法もあります。

vim.api.nvim_create_autocmd('FileType', {
  pattern = 'php',
  callback = function()
    vim.opt_local.iskeyword:append('$')
  end,
})

Neovim（nvim-lspconfig 利用）

nvim-lspconfig プラグインを使う場合は、以下の設定で有効化できます。

require('lspconfig').phpactor.setup({
  cmd = { 'phpactor', 'language-server' },
  root_dir = require('lspconfig.util').root_pattern('composer.json', '.git', '.phpactor.json'),
})

VSCode

Phpactor公式のVSCode拡張 phpactor/vscode-phpactor をインストールします。

VSCode の拡張機能マーケットプレイスで「Phpactor」を検索
インストール後、phpactor コマンドにPATHが通っていれば自動検出されます
PATHが通っていない場合は settings.json でパスを明示します

{
  "phpactor.path": "/home/user/.local/bin/phpactor"
}

Intelephense と併用する場合は、機能の重複を避けるためどちらか一方を無効化するのが望ましいです。

Emacs（lsp-mode）

Emacs の lsp-mode は Phpactor をビルトインでサポートしています。

(use-package lsp-mode
  :hook (php-mode . lsp)
  :config
  (setq lsp-phpactor-path "/home/user/.local/bin/phpactor"))

主要な設定変数は以下のとおりです。

変数名	説明
`lsp-phpactor-path`	phpactor 実行ファイルのパス
`lsp-php-composer-dir`	Composer ディレクトリのパス
`lsp-phpactor-extension-alist`	Phpactor 拡張の関連付け
`lsp-clients-php-server-command`	サーバー起動コマンドのカスタマイズ

Helix / Zed / その他

Helix や Zed は LSP サーバーの自動検出機能を持っています。phpactor がPATH上に存在すれば、PHPファイルを開いた際に自動的に接続されます。Helix の場合は languages.toml で明示的に設定することも可能です。

[[language]]
name = "php"
language-servers = ["phpactor"]

[language-server.phpactor]
command = "phpactor"
args = ["language-server"]

設定ファイルの書き方（.phpactor.json）

Phpactorはプロジェクトルートに配置した .phpactor.json（または .phpactor.yml）で動作をカスタマイズできます。設定ファイルの読み込み優先順位は以下のとおりです。

プロジェクトルート: .phpactor.json
ユーザー設定: ~/.config/phpactor/phpactor.json
システム設定: /etc/xdg/phpactor/phpactor.json

設定ファイルの生成と管理

# 新規設定ファイルをJSON Schemaつきで生成
phpactor config:init

# 現在読み込まれている設定値を全て表示
phpactor config:dump

# プロジェクトの設定ファイルを信頼済みとしてマーク
phpactor config:trust

セキュリティ上、プロジェクトルートの設定ファイルは初回読み込み時に信頼の確認が求められます。config:trust を実行するまで、プロジェクト固有の設定は適用されません。

設定例

以下は一般的なPHP プロジェクト向けの設定例です。

{
  "$schema": "https://phpactor.readthedocs.io/en/master/_static/schema/phpactor.schema.json",
  "language_server_phpstan.enabled": true,
  "language_server_php_cs_fixer.enabled": true,
  "language_server_completion.trim_leading_dollar": true,
  "indexer.exclude_patterns": [
    "/vendor/test/**/*",
    "/vendor/tests/**/*",
    "/node_modules/**/*"
  ]
}

設定ファイル中では、%project_root%、%cache%、%config%、%application_root% といったパストークンが利用できます。

大規模プロジェクトでの性能改善

数十万行以上のコードベースでPhpactorを快適に動かすには、PHPランタイムとPhpactor双方の調整が有効です。

PHP ランタイム設定の最適化

php.ini または環境変数で以下を調整します。

; メモリ上限を引き上げ（大規模プロジェクトでは数GB必要な場合あり）
memory_limit = 4G

; OPcache を有効化して解析速度を向上
opcache.enable_cli = 1
opcache.jit = 1255
opcache.jit_buffer_size = 256M

; xdebug はLSPサーバー実行時に無効化する
; 環境変数で制御: XDEBUG_MODE=off phpactor language-server

xdebug が有効な状態ではインデックス構築やシンボル解析が大幅に遅くなるため、LSPサーバーの実行時は無効化を推奨します。

XDEBUG_MODE=off phpactor language-server

インデクサの事前構築

Phpactorはプロジェクトのシンボル情報をインデックスとして保持しています。初回起動時やファイル変更時に自動構築されますが、大規模プロジェクトでは事前にインデックスを作成しておくとエディタ起動直後の待ち時間を短縮できます。

phpactor index:build -v

不要なディレクトリの除外

vendor 配下のテストコードや node_modules はインデックス対象から外すことで、メモリ使用量と解析時間を削減できます。

{
  "indexer.exclude_patterns": [
    "/vendor/test/**/*",
    "/vendor/tests/**/*",
    "/vendor/*/test/**/*",
    "/vendor/*/tests/**/*",
    "/node_modules/**/*",
    "/storage/**/*"
  ]
}

エディタ側のタイムアウト設定

大規模プロジェクトではLSPレスポンスに時間がかかる場合があります。Emacs lsp-mode では lsp-response-timeout を延長するのが効果的です。

(setq lsp-response-timeout 60)

Neovim の場合はデフォルトで長めに設定されていますが、vim.lsp.buf の各関数にタイムアウトオプションを渡すことも可能です。

Intelephenseとの機能比較

PHP向けLSPサーバーの選択で頻繁に比較されるのがIntelephenseです。両者の特性は以下のように異なります。

比較項目	Phpactor	Intelephense
ライセンス	MIT（完全オープンソース）	フリーミアム（無料版 + 有料プレミアム）
費用	無料	基本無料 / Premium は有料
実装言語	PHP	TypeScript（Node.js）
OS対応	Linux・macOS（Windowsは WSL 経由）	Linux・macOS・Windows
コード補完	クラス名自動インポート対応	高精度、より豊富な補完候補
リファクタリング	変数リネーム・メソッド抽出などビルトイン	無料版では限定的
フォーマット	php-cs-fixer 連携	内蔵フォーマッタ
診断	PHP lint + PHPStan / Psalm 連携	独自の診断エンジン内蔵
初期設定	設定ファイルの作成が必要	インストール直後から動作
拡張性	プラグインアーキテクチャ	拡張API なし

使い分けの指針

設定を自分で組み上げたい・OSS を優先したい → Phpactor
最小限の設定ですぐに使いたい・Windows で開発する → Intelephense
PHPStan や Psalm の診断結果をエディタ上で確認したい → Phpactor（連携機能あり）
大規模 Laravel プロジェクトで安定した補完が必要 → Intelephense（Laravel サポートが充実）

両者を併用することも技術的には可能ですが、補完候補の重複や診断メッセージの競合が発生するため、基本的にはどちらか一方を選択してください。

フレームワーク連携のポイント

Laravel プロジェクトでの注意点

Laravel では Facade やマジックメソッドが多用されるため、静的解析ツールが型情報を正しく認識できない場合があります。以下の対策が有効です。

laravel-ide-helper の導入: composer require --dev barryvdh/laravel-ide-helper でスタブファイルを生成し、Phpactorが型を正しく解決できるようにします
```
php artisan ide-helper:generate
php artisan ide-helper:models --nowrite
php artisan ide-helper:meta
```

スタブパスの設定: 生成されたスタブファイルのパスを .phpactor.json に指定します

{
  "indexer.stub_paths": [
    "%project_root%/_ide_helper.php",
    "%project_root%/_ide_helper_models.php"
  ]
}

インデックスの再構築: スタブ生成後にインデックスを作り直します
```
phpactor index:build
```

Symfony プロジェクト

Symfony はサービスコンテナによる依存注入が中心のフレームワークです。コンテナから取得するサービスの型は PHPDoc で明示しておくと、Phpactorの補完精度が向上します。また、PHPStan の Symfony 拡張（phpstan/phpstan-symfony）を併用すると、コンテナ経由の型解決がさらに正確になります。

よくあるトラブルと解決策

phpactor status でエラーが出る

phpactor status を実行して環境を確認してください。PHP バージョンが 8.1 未満の場合や、mbstring 拡張が無効な場合にエラーが発生します。

php -v          # PHPバージョン確認
php -m | grep mbstring  # mbstring 拡張の確認

補完が遅い・反応しない

xdebug が有効になっていないか確認します（php -m | grep xdebug）
memory_limit が十分か確認します
indexer.exclude_patterns で不要なディレクトリを除外します
phpactor index:build -v でインデックスを手動再構築します

LSPサーバーが起動しない

# 直接実行してエラーメッセージを確認
phpactor language-server -vvv

# TCP モードで起動してデバッグ
phpactor language-server --address=127.0.0.1:8888 -vvv

-vvv オプションで詳細なログが出力されます。接続の問題やPHP拡張の不足などの原因が特定しやすくなります。

設定ファイルが読み込まれない

プロジェクトルートの .phpactor.json は、セキュリティ上の理由で初回は信頼されていない状態です。以下のコマンドで信頼を付与してください。

phpactor config:trust

信頼済みかどうかは phpactor config:dump で確認できます。

LSPサーバーの起動モード

Phpactorは2つのモードでLSPサーバーとして動作します。

STDIO モード（標準）

ほとんどのエディタはこのモードで自動起動します。エディタが標準入出力経由でJSON-RPCメッセージをやり取りします。

phpactor language-server

TCP モード（デバッグ用途）

ネットワーク経由で接続するモードです。LSPメッセージの内容を確認したい場合や、リモート接続のテストに使えます。

phpactor language-server --address=127.0.0.1:8888 -vvv

コミュニティとサポート

Phpactorの開発やサポートは以下のチャネルで行われています。

GitHub Issues / Discussions: phpactor/phpactor でバグ報告や機能リクエストが可能です
Slack: Symfony Devs Slack の #phpactor チャンネル
Mastodon: @phpactor

まとめ

PhpactorはMITライセンスで提供されるPHP製のLSPサーバーです。コード補完、定義ジャンプ、参照検索、リファクタリング、PHPStan / Psalm連携による診断など、日常的なPHP開発に必要なLSP機能を幅広くカバーしています。Neovim 0.11のネイティブLSP対応やVSCode拡張により、セットアップの手間も以前より大幅に減っています。

大規模プロジェクトでは、OPcacheの有効化やxdebugの無効化、インデックス除外パターンの設定といったチューニングが動作速度に直結します。Intelephenseとの選択は、OSS志向・設定のカスタマイズ性を重視するならPhpactor、手軽さやWindows対応を求めるならIntelephenseという判断基準が明確です。

PHPの開発環境をエディタに依存しない形で整備したい場合、Phpactorは有力な選択肢となります。

LSPとPhpactorの位置づけ#

Phpactorが対応するLSP機能#

対応済み機能#

未対応の機能#

インストール手順#

PHAR ファイル（推奨）#

Git Clone + Composer#

パッケージマネージャ経由#

動作確認#

エディタ別セットアップ#

Neovim（0.11以降 ネイティブLSP）#

補完時のドルマーク問題への対処#

Neovim（nvim-lspconfig 利用）#

VSCode#

Emacs（lsp-mode）#

Helix / Zed / その他#

設定ファイルの書き方（.phpactor.json）#

設定ファイルの生成と管理#

設定例#

大規模プロジェクトでの性能改善#

PHP ランタイム設定の最適化#

インデクサの事前構築#

不要なディレクトリの除外#

エディタ側のタイムアウト設定#

Intelephenseとの機能比較#

使い分けの指針#

フレームワーク連携のポイント#

Laravel プロジェクトでの注意点#

Symfony プロジェクト#

よくあるトラブルと解決策#

phpactor status でエラーが出る#

補完が遅い・反応しない#

LSPサーバーが起動しない#

設定ファイルが読み込まれない#

LSPサーバーの起動モード#

STDIO モード（標準）#

TCP モード（デバッグ用途）#

コミュニティとサポート#

まとめ#