IntelephenseでPHP開発を効率化｜LSPサーバーの導入から実践設定まで

PHPプロジェクトの規模が大きくなるほど、コード補完や定義ジャンプの精度が生産性を左右します。Language Server Protocol（LSP）に対応したサーバーを導入すれば、エディタを問わずこれらの機能を高品質に利用できます。PHP向けLSPサーバーの中でも、Intelephenseはインデックス速度・補完精度・メモリ効率の面で多くの開発者に支持されています。

ここでは、Intelephenseの基本的な仕組みから、主要エディタごとの導入手順、無料版とPremium版の機能差、大規模プロジェクトでのパフォーマンスチューニングまで、実務で必要になる情報をまとめています。

LSP（Language Server Protocol）の基本的な仕組み

LSPは、Microsoftが2016年に策定したエディタと言語解析エンジン間の通信規格です。従来はエディタごとに言語サポートプラグインを個別開発する必要がありましたが、LSPの登場により「1つの言語サーバーを作れば、あらゆるLSP対応エディタで利用できる」というエコシステムが成立しました。

クライアント・サーバーモデル

LSPはJSON-RPCベースのプロトコルで、以下の流れで動作します。

1. エディタ（LSPクライアント） がファイルを開くと、言語サーバープロセスを起動
2. 言語サーバー がプロジェクト全体をインデックスし、構文解析・型解析を実行
3. エディタからの要求（補完・定義ジャンプ・ホバー情報など）に対して、サーバーが解析結果を返却
4. ファイル変更時はインクリメンタルに差分解析を実行

この仕組みにより、VS Code・Neovim・Emacs・Sublime Textなど、LSPクライアント機能を持つエディタであれば同一の言語サーバーを共有できます。

LSPが提供する主な機能

Intelephenseの特徴と他のPHP LSPサーバーとの違い

PHP向けのLSPサーバーは複数存在しますが、それぞれ設計思想や得意分野が異なります。

PHP向け主要LSPサーバーの比較

Intelephenseの強みは、TypeScriptで実装されているためNode.js上で軽快に動作する点と、PHPStubsを活用した高精度な型推論です。大規模なコードベースでも安定した補完精度を維持できます。

Phpactorの強みは、リファクタリング機能が標準で充実している点です。クラスの移動・メソッドの抽出・インターフェースの生成などを無料で利用できます。ただし、PHP自体で実装されているため、起動速度はIntelephenseに劣る場合があります。

**PHP Language Server（felixfbecker版）**は現在メンテナンスが停止しているため、新規導入は推奨されません。

エディタ別のIntelephenseセットアップ手順

VS Code での導入

VS CodeではIntelephenseが最も広く利用されています。

手順：

1. VS Codeの拡張機能マーケットプレイスで「Intelephense」を検索
2. PHP Intelephense（作者: Ben Mewburn）をインストール
3. VS Code組み込みのPHP言語機能との競合を避けるため、以下の設定を追加

// settings.json
{
  "php.suggest.basic": false,
  "php.validate.enable": false
}

この2つの設定により、VS Codeデフォルトの簡易的なPHP補完と構文チェックが無効化され、Intelephenseの高精度な解析に一本化されます。

動作確認：

PHPファイルを開き、クラス名やメソッドの補完候補が表示されること、定義元へのジャンプ（F12キー）が動作することを確認します。ステータスバーにIntelephenseのインデックス進捗が表示されます。

Neovim での導入

Neovimでは、nvim-lspconfigプラグインを使ってIntelephenseを設定します。

前提条件：

• Node.js（v20以上、LTS推奨）がインストール済み
• Neovim 0.5以上

Intelephenseのグローバルインストール：

npm install -g intelephense

nvim-lspconfigでの設定例（init.lua）：

-- LSPの基本設定
local lspconfig = require('lspconfig')

lspconfig.intelephense.setup({
  cmd = { "intelephense", "--stdio" },
  filetypes = { "php" },
  root_dir = lspconfig.util.root_pattern("composer.json", ".git"),
  settings = {
    intelephense = {
      stubs = {
        "apache", "bcmath", "bz2", "calendar", "com_dotnet",
        "Core", "ctype", "curl", "date", "dba", "dom",
        "enchant", "exif", "FFI", "fileinfo", "filter",
        "fpm", "ftp", "gd", "gettext", "gmp", "hash",
        "iconv", "imap", "intl", "json", "ldap",
        "libxml", "mbstring", "meta", "mysqli", "oci8",
        "odbc", "openssl", "pcntl", "pcre", "PDO",
        "pdo_ibm", "pdo_mysql", "pdo_pgsql", "pdo_sqlite",
        "pgsql", "Phar", "posix", "pspell", "readline",
        "Reflection", "session", "shmop", "SimpleXML",
        "snmp", "soap", "sockets", "sodium", "SPL",
        "sqlite3", "standard", "superglobals", "sysvmsg",
        "sysvsem", "sysvshm", "tidy", "tokenizer", "xml",
        "xmlreader", "xmlrpc", "xmlwriter", "xsl", "Zend OPcache",
        "zip", "zlib",
        "wordpress"  -- WordPressプロジェクトの場合に追加
      },
      files = {
        maxSize = 5000000,  -- 解析対象ファイルの最大サイズ（バイト）
      },
      environment = {
        phpVersion = "8.3",  -- プロジェクトのPHPバージョンに合わせる
      },
    },
  },
  on_attach = function(client, bufnr)
    -- キーマッピングの設定
    local opts = { noremap = true, silent = true, buffer = bufnr }
    vim.keymap.set('n', 'gd', vim.lsp.buf.definition, opts)
    vim.keymap.set('n', 'K', vim.lsp.buf.hover, opts)
    vim.keymap.set('n', 'gi', vim.lsp.buf.implementation, opts)
    vim.keymap.set('n', 'gr', vim.lsp.buf.references, opts)
    vim.keymap.set('n', '<leader>rn', vim.lsp.buf.rename, opts)
    vim.keymap.set('n', '<leader>ca', vim.lsp.buf.code_action, opts)
  end,
})

Emacs での導入

Emacsではlsp-modeまたはeglotを使用します。

lsp-modeでの設定例：

;; lsp-modeのインストール（use-package利用）
(use-package lsp-mode
  :ensure t
  :hook (php-mode . lsp-deferred)
  :commands lsp)

(use-package lsp-ui
  :ensure t
  :commands lsp-ui-mode)

Intelephenseがグローバルインストールされていれば、lsp-modeが自動的に検出します。

eglot（Emacs 29以降の組み込みLSPクライアント）での設定例：

(add-hook 'php-mode-hook 'eglot-ensure)

;; Intelephenseのパスを明示する場合
(add-to-list 'eglot-server-programs
             '(php-mode . ("intelephense" "--stdio")))

Sublime Text での導入

Sublime Textでは「LSP」パッケージを利用します。

1. Package Controlから「LSP」をインストール
2. Preferences > Package Settings > LSP > Settings に以下を追記

{
  "clients": {
    "intelephense": {
      "enabled": true,
      "command": ["intelephense", "--stdio"],
      "selector": "source.php",
      "initializationOptions": {
        "licenceKey": ""
      }
    }
  }
}

無料版とPremium版の機能比較

Intelephenseは基本的な機能を無料で提供しつつ、高度な機能をPremium版（有料ライセンス）で提供しています。ライセンスキーの購入はIntelephenseの公式サイト（intelephense.com）から行えます。

機能差の詳細

無料版だけでもコード補完・定義ジャンプ・ホバー情報・診断・コードフォーマットといった日常的な開発に必要な機能は揃っています。リネームやコードアクション（自動import等）を頻繁に使う場合や、チーム全体の開発効率を重視する場合はPremium版の導入を検討してください。

Premium版ライセンスの有効化

VS Codeの場合、コマンドパレット（Ctrl+Shift+P）から「Intelephense: Enter licence key」を実行してライセンスキーを入力します。

Neovimの場合は、init.luaの設定に以下を追加します。

settings = {
  intelephense = {
    licenceKey = "YOUR_LICENCE_KEY",
  },
}

フレームワーク別の推奨設定

Laravel プロジェクト

Laravelではファサードやヘルパー関数が多用されるため、追加の設定で補完精度を高められます。

1. Laravel IDE Helperの導入：

composer require --dev barryvdh/laravel-ide-helper
php artisan ide-helper:generate
php artisan ide-helper:models --nowrite
php artisan ide-helper:meta

これにより _ide_helper.php、_ide_helper_models.php、.phpstorm.meta.php が生成され、Intelephenseがファサードやモデルのメソッドを正確に解析できるようになります。

2. スタブの追加設定（Neovimの場合）：

settings = {
  intelephense = {
    stubs = {
      -- 標準スタブに加えて
      "redis",    -- Redisを使う場合
      "memcached" -- Memcachedを使う場合
    },
    environment = {
      includePaths = {
        "vendor/laravel/framework/src",
      },
    },
  },
}

WordPress プロジェクト

WordPressの関数やフック名を補完するには、スタブ設定にwordpressを追加します。

{
  "intelephense.stubs": [
    "apache", "bcmath", "Core", "curl", "date",
    "dom", "fileinfo", "json", "mbstring", "mysqli",
    "pcre", "Phar", "readline", "Reflection", "session",
    "SimpleXML", "SPL", "standard", "superglobals",
    "tokenizer", "xml", "xmlreader", "xmlwriter",
    "zip", "zlib",
    "wordpress"
  ]
}

加えて、wp-content/plugins/ や wp-content/themes/ 配下のコードが解析対象に含まれているか、intelephense.files.associationsで確認しておくと安心です。

パフォーマンスの最適化

プロジェクトの規模が大きい場合や、解析が遅いと感じる場合は以下の設定を検討します。

解析対象の制御

不要なディレクトリを除外することで、インデックス時間とメモリ消費を削減できます。

{
  "intelephense.files.exclude": [
    "**/node_modules/**",
    "**/vendor/**/{Tests,tests}/**",
    "**/.git/**",
    "**/storage/**",
    "**/public/build/**"
  ]
}

vendorディレクトリ内のテストコードは補完には不要なケースがほとんどです。除外設定を追加するとインデックスサイズが大幅に縮小します。

ファイルサイズ上限の調整

デフォルトでは1MBを超えるPHPファイルは解析対象外です。自動生成コードなどで大きなファイルがある場合は上限を変更できます。

{
  "intelephense.files.maxSize": 3000000
}

ただし、上限を上げすぎるとメモリ消費が増加するため、必要な範囲に留めてください。

メモリ使用量の監視

Node.jsのデフォルトヒープサイズでは大規模プロジェクトで不足する場合があります。VS Codeの設定でNode.jsのメモリ上限を引き上げることも可能です。

{
  "intelephense.runtime": "node",
  "intelephense.maxMemory": 4096
}

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

補完が表示されない

原因1: VS Code組み込みのPHP機能との競合

settings.jsonで以下が設定されているか確認します。

{
  "php.suggest.basic": false,
  "php.validate.enable": false
}

原因2: インデックスが完了していない

大規模プロジェクトでは初回インデックスに数分かかる場合があります。ステータスバーの進捗表示を確認してください。インデックスが完了しない場合は、キャッシュをクリアして再構築します。

VS Codeのコマンドパレットから「Intelephense: Index workspace」を実行すると、インデックスを再構築できます。

原因3: Node.jsのバージョンが古い

Intelephenseの動作にはNode.js 20以上（LTS推奨）が必要です。node -vでバージョンを確認し、必要に応じてアップデートしてください。

型エラーの誤検出

PHPDocコメントと実際のコードの型が一致しない場合、Intelephenseが誤った診断を出すことがあります。

対処法1: PHPDocを修正する

/**
 * @param array<string, mixed> $config  // 具体的な型を記述
 * @return \App\Models\User|null
 */
public function findUser(array $config): ?User
{
    // ...
}

対処法2: 特定の診断を無効化する

{
  "intelephense.diagnostics.undefinedTypes": false,
  "intelephense.diagnostics.undefinedFunctions": false
}

ただし、診断を無効化するとバグの検出力が低下するため、根本的にはPHPDocを正確に記述する方が望ましいです。

vendor配下のクラスが補完されない

composer installを実行してもvendor内のクラスが補完に出ない場合は、以下を確認します。

1. intelephense.files.excludeでvendorディレクトリ全体を除外していないか
2. composer.jsonのautoload設定が正しいか
3. コマンドパレットから「Intelephense: Index workspace」を実行して再インデックス

Intelephenseの設定リファレンス（主要項目）

頻繁に調整する設定項目をまとめます。

まとめ

IntelephenseはPHP開発における生産性を大きく向上させるLSPサーバーです。無料版でもコード補完・定義ジャンプ・診断・フォーマット機能を利用でき、Premium版ではリネーム・コードアクション・型階層表示など高度な機能が追加されます。VS Code・Neovim・Emacs・Sublime Textのいずれのエディタでも、LSPの仕組みを通じて統一された開発体験を実現できます。

プロジェクトの特性に合わせてスタブ設定やファイル除外設定を調整することで、補完精度とパフォーマンスの両立が可能です。Laravel IDE HelperやWordPressスタブの活用も、フレームワーク固有の開発効率を高める有効な手段です。