VSCodeでPHPのIntelephenseを使う方法

VSCodeでPHPを開発するなら、「PHP Intelephense」を導入するとコード補完や定義ジャンプ、参照検索、静的解析などが使いやすくなります。

IntelephenseはPHP向けのLanguage Serverで、VSCodeのPHP開発環境をより高機能にするための拡張機能です。

PHP単体の小規模な開発だけでなく、Composerを利用したプロジェクトや、Laravel・Symfonyなどのフレームワークを使った開発でも活用できます。

ここでは、VSCodeにIntelephenseを導入する方法から基本設定、使い方、トラブル時の対処方法まで詳しく解説します。

Intelephenseとは

Intelephenseは、PHPコードを解析してVSCodeに各種開発支援機能を提供するLanguage Serverです。

代表的な機能として、次のようなものがあります。

• PHPコードの自動補完
• クラスやメソッドの候補表示
• 関数やメソッドの引数情報表示
• 定義へのジャンプ
• 参照箇所の検索
• シンボル検索
• PHPDocの認識
• 型情報を利用した静的解析
• 未定義クラスや未定義メソッドの検出
• コードフォーマット
• 名前空間やuse宣言の解析

無料版でも基本的なコード補完やナビゲーション、診断、フォーマット機能などを利用できます。

一方で、Rename、CodeLens、Inlay Hints、Type Hierarchy、Code Actionsなど、一部の高度な機能はPremium版で提供されています。

Intelephenseをインストールする方法

拡張機能画面からインストールする

まずVSCodeを起動し、左側の「拡張機能」アイコンをクリックします。

WindowsやLinuxでは、次のショートカットでも拡張機能画面を開けます。

Ctrl + Shift + X

検索欄に、次のように入力します。

Intelephense

検索結果に表示される「PHP Intelephense」を選択し、「インストール」をクリックします。

拡張機能IDは次のとおりです。

bmewburn.vscode-intelephense-client

同名や類似名の拡張機能と間違えないように、PublisherがBen Mewburnであることも確認しておくと安心です。

コマンドからインストールする

VSCodeのcodeコマンドを利用できる環境では、ターミナルからインストールすることもできます。

code --install-extension bmewburn.vscode-intelephense-client

通常はインストール後すぐに利用できます。

補完や解析が正常に動作しない場合は、VSCodeを再読み込みするか再起動してみてください。

VSCode標準のPHP機能との競合を避ける

Intelephenseを導入する際は、VSCode標準のPHP補完機能との競合に注意が必要です。

Intelephense公式では、組み込みの「PHP Language Features」を無効にする方法が推奨されています。

PHP Language Featuresを無効にする

拡張機能画面を開き、検索欄に次のように入力します。

@builtin php

表示された組み込み拡張機能の中から、

PHP Language Features

を無効にします。

一方、

PHP Language Basics

はPHPのシンタックスハイライトなどを提供するため、通常は有効なままにします。

補完だけを無効にする方法

PHP Language Features全体を無効にせず、VSCode標準の基本補完のみを止める方法もあります。

settings.jsonに次の設定を追加します。

{
    "php.suggest.basic": false
}

Intelephense公式の推奨に従うならPHP Language Features自体を無効にする方法が分かりやすいですが、補完の重複だけを解消したい場合はphp.suggest.basicを利用する方法もあります。

PHPプロジェクトをフォルダーとして開く

Intelephenseを使うときは、PHPファイルを1つだけ開くよりも、プロジェクト全体をフォルダーとして開くことが重要です。

たとえば、次のような構成のプロジェクトがあるとします。

sample-project/
├── public/
│ └── index.php
├── src/
│ ├── Controller/
│ └── Service/
├── vendor/
├── composer.json
└── composer.lock

VSCodeではsample-projectフォルダー全体を開きます。

ターミナルから開く場合は、次のように実行できます。

cd sample-project
code .

Intelephenseはワークスペース内のPHPファイルをインデックス化し、クラスや関数、メソッドなどの情報を解析します。

ファイルを単独で開いていると、プロジェクト内の他のクラスを認識できず、補完や定義ジャンプが十分に機能しない場合があります。

Intelephenseでコード補完を使う

Intelephenseをインストールすると、PHPコードの入力中に補完候補が表示されます。

たとえば、次のようなコードを書いたとします。

<?php

class User
{
    public function getName(): string
    {
        return 'Taro';
    }
}

$user = new User();

$user->

$user->まで入力すると、getName()などの候補が表示されます。

補完候補が自動表示されない場合は、次のショートカットで手動表示できます。

Ctrl + Space

型宣言を利用すると補完精度が上がる

Intelephenseは型情報を利用してコードを解析します。

そのため、引数型や戻り値型を明示すると補完精度が高くなります。

<?php

class User
{
    public function getName(): string
    {
        return 'Taro';
    }
}

function findUser(): User
{
    return new User();
}

$user = findUser();

$user->getName();

findUser()の戻り値がUserと定義されているため、Intelephenseは$userをUser型として認識できます。

定義へジャンプする

Intelephenseが提供する定義情報を利用して、クラスやメソッドの定義元へ移動できます。

たとえば、

$user->getName();

のgetName上で操作します。

WindowsやLinuxでは、一般的に次の操作が利用できます。

F12

または、

Ctrl + クリック

右クリックメニューから「定義へ移動」を選択することもできます。

LaravelやSymfonyなど、ファイル数が多いプロジェクトでは特に便利です。

定義をその場で確認する

別ファイルへ移動せずに定義内容を確認したい場合は、VSCodeの「定義をここに表示」を利用できます。

WindowsやLinuxでは、一般的に次のショートカットです。

Alt + F12

これはVSCode側の機能ですが、Intelephenseが提供した定義情報を利用して表示されます。

コードを追いかけながら元のファイルを開いたまま確認したい場合に便利です。

参照箇所を検索する

Intelephenseを利用すると、クラスやメソッドがどこから使用されているのかを検索できます。

たとえば、次のようなメソッドがあるとします。

class UserService
{
    public function createUser(): void
    {
    }
}

createUser上で右クリックし、「すべての参照を検索」などを選択すると、そのメソッドを利用している箇所を確認できます。

リファクタリングや不要なコードを調査するときに便利です。

型情報や説明を確認する

変数や関数、メソッドなどにマウスカーソルを合わせると、型情報やシグネチャを確認できます。

たとえば、

strlen($value);

のstrlenにカーソルを合わせると、引数や戻り値の情報などが表示されます。

自作クラスでもPHPDocを書いておくと、説明を確認しやすくなります。

/**
 * ユーザー名を取得します。
 */
public function getName(): string
{
    return $this->name;
}

PHPDocは補完や可読性の向上にも役立ちます。

シグネチャヘルプを使う

関数やメソッドを入力すると、必要な引数情報も表示されます。

たとえば、

array_map(

と入力すると、関数の引数情報を確認できます。

自作メソッドでも同様です。

public function createUser(
    string $name,
    string $email
): User {
    // 処理
}

この状態で、

$service->createUser(

と入力すると、$nameや$emailなどの引数情報を確認できます。

IntelephenseでPHPコードを静的解析する

IntelephenseはPHPコードを解析し、問題がある可能性のある箇所をVSCode上に表示します。

たとえば、存在しないクラスを指定すると、

$user = new UnknownClass();

未定義の型として警告される場合があります。

存在しないメソッドについても、

$user->unknownMethod();

のようなコードを検出できます。

ただし、Intelephenseの診断はPHPを実際に実行した結果ではありません。

あくまでソースコードを解析する静的解析なので、実行時エラーと完全に一致するとは限りません。

PHP本体とIntelephenseの違い

IntelephenseとPHP本体は役割が異なります。

Intelephenseは主に次の役割を担当します。

コード補完
静的解析
定義情報
参照情報
型情報

一方、PHP本体は次の役割を担当します。

PHPコードの実行
php -lによる構文チェック

そのため、Intelephenseを導入しただけではPHPコードそのものを実行できるようになるわけではありません。

PHPがインストールされているか確認する

ターミナルで次のコマンドを実行します。

php -v

PHPがインストールされていれば、バージョン情報が表示されます。

PHP実行ファイルのパスを設定する

VSCode標準のPHP lintを利用する場合、PHP実行ファイルがPATHに登録されていなければphp.validate.executablePathを設定できます。

WindowsでPHPを次の場所に配置している場合、

C:\php\php.exe

settings.jsonに次のように設定します。

{
    "php.validate.executablePath": "C:/php/php.exe"
}

XAMPPを使用している場合は、環境によって次のようになります。

{
    "php.validate.executablePath": "C:/xampp/php/php.exe"
}

Linuxでは、一例として次のようになります。

{
    "php.validate.executablePath": "/usr/bin/php"
}

macOSでは、次のコマンドでPHPの場所を確認できます。

which php

IntelephenseのPHPバージョンを設定する

Intelephenseでは、解析対象として扱うPHPバージョンを設定できます。

設定項目は次のとおりです。

intelephense.environment.phpVersion

たとえばPHP 8.3系のプロジェクトなら、次のように設定できます。

{
    "intelephense.environment.phpVersion": "8.3.0"
}

この設定は、Intelephenseが静的解析時にどのPHPバージョンを基準にするかを決めるものです。

実際に実行されるPHPのバージョンを変更する設定ではありません。

つまり、次の2つは役割が異なります。

intelephense.environment.phpVersion
→ Intelephenseの静的解析用

php.validate.executablePath
→ PHP実行ファイル・VSCode標準lint用

この違いを理解しておくと設定時に混乱しにくくなります。

settings.jsonでIntelephenseを設定する

VSCodeでは設定画面から変更するほか、settings.jsonを直接編集することもできます。

コマンドパレットを開きます。

Ctrl + Shift + P

「Preferences: Open User Settings (JSON)」や「Preferences: Open Workspace Settings (JSON)」を選択します。

プロジェクトごとに設定を分けたい場合は、.vscode/settings.jsonを利用すると便利です。

たとえば、次のように設定できます。

{
    "php.suggest.basic": false,

    "[php]": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "bmewburn.vscode-intelephense-client"
    },

    "intelephense.files.exclude": [
        "**/.git/**",
        "**/.svn/**"
    ]
}

必要な項目だけを設定してください。

保存時にPHPコードをフォーマットする

IntelephenseにはPSR-12互換のフォーマット機能があります。

PHPのデフォルトフォーマッターとして利用する場合は、次のように設定できます。

{
    "[php]": {
        "editor.defaultFormatter": "bmewburn.vscode-intelephense-client",
        "editor.formatOnSave": true
    }
}

この設定を行うと、PHPファイルを保存したタイミングで自動整形されます。

ただし、チーム開発ではIntelephense以外のフォーマットツールを採用している場合もあります。

たとえば、

PHP CS Fixer
PHP_CodeSniffer
Laravel Pint

などです。

すでにプロジェクトでコーディング規約用ツールが決まっている場合は、そのツールを優先したほうがよいでしょう。

不要なフォルダーを解析対象から除外する

大規模なプロジェクトでは、不要なファイルまで解析するとインデックス作成に時間がかかることがあります。

その場合は、

intelephense.files.exclude

を利用できます。

たとえば、次のように設定します。

{
    "intelephense.files.exclude": [
        "**/.git/**",
        "**/.svn/**",
        "**/node_modules/**"
    ]
}

ただし、PHPの補完に必要なディレクトリまで除外しないよう注意してください。

特にComposerのvendorディレクトリには依存ライブラリのPHPクラスが含まれています。

vendorを除外すると、外部ライブラリの補完や定義ジャンプに影響する可能性があるため、単に容量が大きいという理由だけで除外するのは避けたほうがよいでしょう。

ワークスペース外のPHPファイルを認識させる

プロジェクト外にある共通ライブラリなどをIntelephenseに認識させたい場合は、

intelephense.environment.includePaths

を利用できます。

たとえば、外部ディレクトリのPHPコードを参照しているプロジェクトでは、includePathsに対象パスを追加することで解析対象に含められます。

複数フォルダーを含むワークスペースで相互参照する場合にも役立つことがあります。

PHP以外の拡張子をPHPとして扱う

独自拡張子のファイルにPHPコードが含まれている場合は、VSCodeのfiles.associationsでPHPとして認識させることができます。

たとえば、.moduleファイルをPHPとして扱う場合は次のようにします。

{
    "files.associations": {
        "*.module": "php"
    }
}

files.associationsとintelephense.files.associationsの違い

似た名前の設定として、

files.associations

と、

intelephense.files.associations

があります。

役割は異なります。

files.associations
→ VSCode側でファイルの言語モードをPHPとして認識させる

intelephense.files.associations
→ Intelephense側でPHPファイルとして解析する対象を指定する

設定を変更するときは、両者を混同しないようにしましょう。

ComposerとIntelephenseを組み合わせる

ComposerはIntelephenseを使うための必須条件ではありません。

単純なPHPファイルでもIntelephenseは利用できます。

ただし、LaravelやSymfony、PHPUnitなど外部ライブラリを利用するプロジェクトでは、Composerとの組み合わせが重要になります。

Gitからプロジェクトを取得した直後など、依存パッケージがまだインストールされていない場合は、

composer install

を実行します。

これによりvendorディレクトリなどが生成されます。

依存ライブラリが存在しない状態では、Intelephenseが外部クラスを認識できず、

Undefined type
Undefined method

などの警告が表示されることがあります。

Undefined typeが表示される場合の対処方法

Intelephenseでよく見かける警告の一つが「Undefined type」です。

たとえば、

$user = new User();

のUserに警告が表示される場合があります。

考えられる原因として、次のようなものがあります。

• 対象クラスがワークスペースに存在しない
• Composerパッケージがインストールされていない
• namespaceが間違っている
• use宣言が間違っている
• プロジェクトフォルダーではなくファイル単体を開いている
• ワークスペース外のクラスを参照している
• Intelephenseのインデックスが古い
• フレームワークが動的にクラスやプロパティを生成している

まず、コードの名前空間やuse宣言を確認しましょう。

<?php

namespace App\Service;

use App\Entity\User;

class UserService
{
    public function find(): User
    {
        return new User();
    }
}

コード自体に問題がない場合は、Composerの依存関係やインデックスの状態を確認します。

Intelephenseのキャッシュやインデックスを更新する

コードが正しいにもかかわらず補完や定義ジャンプがおかしい場合は、Intelephenseのインデックスが古くなっている可能性があります。

コマンドパレットを開きます。

Ctrl + Shift + P

続けて、

Intelephense

と入力し、利用可能なキャッシュ削除やインデックス関連のコマンドを確認します。

表示されるコマンド名は拡張機能のバージョンによって変わる可能性があるため、現在のVSCode上に表示されている名称を使用するのが確実です。

Composerパッケージを変更した後やGitのブランチを大きく切り替えた後などに、再インデックスで改善することがあります。

Intelephenseが動かない場合の確認ポイント

PHPファイルとして認識されているか確認する

VSCode右下の言語モードを確認します。

正しく認識されている場合は、

PHP

と表示されます。

Plain Textなどになっている場合は、言語モードをPHPに変更してください。

プロジェクトフォルダーを開いているか確認する

test.phpだけを単独で開くのではなく、プロジェクトのルートフォルダーを開きます。

project/
├── src/
├── vendor/
├── composer.json
└── test.php

この場合はprojectフォルダー全体を開きます。

PHP関連拡張機能が競合していないか確認する

複数のPHP Language Serverを同時に有効にしていると、次のような問題が発生することがあります。

• 補完候補が重複する
• 診断結果が二重に表示される
• 定義ジャンプの動作が不安定になる
• フォーマッターが競合する

同じ役割のPHP拡張機能を複数利用している場合は、不要なものを一時的に無効にして確認してみてください。

LaravelでIntelephenseを使う方法

LaravelでもIntelephenseは利用できます。

通常のクラスやモデルであれば、次のようなコードで補完や定義ジャンプを利用できます。

use App\Models\User;

$user = User::find(1);

ただし、Laravelでは静的解析だけでは完全に型を判断しにくい仕組みも多く使われています。

たとえば、

• Facade
• Magic Method
• Magic Property
• Service Container
• Eloquentの動的プロパティ
• 動的スコープ

などです。

そのため、実際には正常に動作するコードでもIntelephenseが一部のメソッドやプロパティを認識できない場合があります。

PHPDocやIDE Helperを併用する

Laravelで補完精度を高めたい場合は、次のような方法があります。

• PHPDocを適切に記述する
• Laravel向けIDE Helperを利用する
• Laravel向けVSCode拡張機能を併用する
• 型宣言を可能な範囲で明示する

ただし、Intelephenseの警告が表示された場合は、最初から無視するのではなく、まずnamespaceやuse宣言、Composerの依存関係、型定義などに問題がないか確認することが大切です。

Intelephenseの無料版とPremium版の違い

Intelephenseは無料版でもPHP開発に必要な基本機能を利用できます。

無料版で利用できる主な機能

無料版では、主に次のような機能を利用できます。

コード補完
Signature Help
定義ジャンプ
参照検索
シンボル検索
診断
フォーマット
Hover
シンボルハイライト
型解析

通常のPHP開発であれば、無料版でも十分に活用できます。

Premium版で利用できる主な機能

Premium版では、さらに次のような機能が追加されます。

Rename
Code Actions
CodeLens
Type Hierarchy
Inlay Hints
Find Implementations
Go to Type Definition
Go to Declaration
Smart Select
Document Links

まずは無料版を使用し、必要な機能がある場合にPremium版を検討するとよいでしょう。

VSCodeでPHPを開発するときの役割分担

Intelephenseを使う場合は、それぞれの機能の役割を理解しておくと設定しやすくなります。

PHP Language Basics
    ↓
PHPのシンタックスハイライト

PHP Intelephense
    ↓
コード補完・静的解析・型情報・シンボル情報

VSCode
    ↓
定義ジャンプ・Peek・参照検索などのUI

PHP本体
    ↓
PHPコードの実行・php -lによる構文チェック

Xdebug
    ↓
ブレークポイントを使った実行時デバッグ

特に重要なのは、IntelephenseはPHP実行環境ではないという点です。

コード補完や静的解析はIntelephenseが担当しますが、PHPコードを実際に実行するにはPHP本体が必要です。

デバッグを行う場合は、さらにXdebugなどのデバッグ環境を用意します。

まとめ

VSCodeでPHP開発を行う場合、Intelephenseを導入するとコード補完や定義ジャンプ、参照検索、静的解析などを利用でき、開発効率を高められます。

基本的な導入手順は次のとおりです。

PHP Intelephenseをインストール
    ↓
VSCode標準の重複するPHP補完機能を整理
    ↓
PHPプロジェクトをフォルダーとして開く
    ↓
IntelephenseがPHPコードをインデックス
    ↓
コード補完・定義ジャンプ・参照検索などを利用

特に重要なのは、プロジェクトフォルダー全体を開くこと、PHP Language Featuresとの競合を避けること、そしてプロジェクトに合わせてintelephense.environment.phpVersionを設定することです。

また、php.validate.executablePathはPHP実行ファイルを指定する設定、intelephense.environment.phpVersionはIntelephenseの静的解析用設定であり、役割が異なります。

この違いを理解したうえで設定すれば、PHP単体の開発からComposer、Laravel、Symfonyを利用したプロジェクトまで、VSCodeをPHP開発環境として活用しやすくなります。

以上、VSCodeでPHPのIntelephenseを使う方法についてでした。

最後までお読みいただき、ありがとうございました。