ワークスペースに WordPress 本体が無くても VS Code の PHP 補完を効かせる — dev container × Intelephense

本記事は、公式 WordPress Docker で 自作テーマ・プラグイン以外を git 管理外にしつつ快適に開発する（+ Claude Code 対応） の派生記事です。

サマリ

• VS Code Dev Containers + Docker 公式 WordPress image で開発していると、自作テーマから get_template_part() 等の WordPress 本体の関数定義 をエディタが解決できず、エラー表示（赤線）となってしまいます
• 解決法: .vscode/settings.json の intelephense.environment.includePaths に コンテナ内の WordPress パス /var/www/html/wp-admin と /var/www/html/wp-includes を渡す
• workspace ツリーには出ないが、シンボル解決などVS Code上でのサポートが効くようになる
• WordPress 以外でも、composer の vendor/ のように ワークスペースには置きたくないが補完は効かせたい ライブラリ群を扱う場面で同様に有効です。

前提環境

• VS Code + Dev Containers 拡張 (Docker)
• Docker ベースイメージに公式 WordPress image を使っている（例: wordpress:6.9-php8.4-apache）
• Intelephense 拡張
• ワークスペース内では自作テーマ・プラグインのみ git 管理、wp-admin/ wp-includes/ はホストのワークスペースに存在しない
• 開発用 WordPress は、公式 Docker image の特定ディレクトリに、自作テーマ・プラグインを bind マウントすることで動作させている

つまり以下のような構成です:

ワークスペース(repo):
├── wordpress/
│   └── wp-content/
│       └── themes/mytheme/   ← 自作テーマ（git 管理）
└── docker-compose.yml

コンテナ内 /var/www/html/:
├── wp-admin/                    ← 公式 image より
├── wp-includes/                 ← 同じ
└── wp-content/                  ← ホストの wordpress/wp-content/ を bind mount
    └── themes/mytheme/

ホスト側、および、ワークスペースに WordPress 本体（wp-admin/ wp-includes/）が無いので、自作テーマの .php を開いた時に get_template_part() が解決できずエラーになり、エディタ画面が赤線だらけになります。

解決策

.vscode/settings.json に以下を追加:

{
  "intelephense.environment.includePaths": [
    "/var/www/html/wp-admin",
    "/var/www/html/wp-includes"
  ]
}

設定後、VS Code を Reload Window（または Reopen in Container）すれば Intelephense が再索引を始めます。自作テーマから WordPress 本体の関数に F12 で飛べるようになるなど、エディタのサポートを受けられるようになります。

検討した案（不採用）

案 1: php-stubs を入れる

composer require --dev php-stubs/wordpress-stubs

vendor/php-stubs/wordpress-stubs/ に WordPress 関数の宣言が入ったスタブが置かれます。エディタはこれを使って型情報を出してくれます。

非常に管理しやすく、vendor を .gitignore すればよいので、git上の管理も簡単です。

問題点:

• スタブは 宣言だけ なので、定義元にジャンプしてもスタブファイルが開き、実際のコードを参照できない。
• composer を導入する必要がある

「型情報だけほしい」用途なら簡便ですが、今回は WordPress 本体側の実装をコードで確認したかったので採用しませんでした。

案 2: WordPress 本体・プラグインのファイルをワークスペースに乗せる

「WordPress サイトの .gitignore レシピ — 自作テーマだけ git 管理するパターン」(https://qiita.com/akatsuki39/items/086dd0b3cf9e2814e0a8)

上記の構成で .gitignore を整えていれば、本番サーバのファイルを取得するか、Docker 公式 WordPress image から WordPress 本体のファイルを抽出して、.git 管理外でワークスペースに置くことも可能ではあります。

問題点:

• WordPress バージョン更新のたびに再抽出する必要がある
• ホストのワークスペース（repo）を クリーンに保つことが当初の動機だったのに合わない
• 本番から同期する場合、本番シークレットが入ったファイルを除外するなど事故が起きないように注意する必要があります

git 管理対象は最小限にしつつ実際の WordPress ファイル一式も置けるので、本番環境にできるだけ近づけたい場合には有効です。

ただ、本構成の目的（ワークスペースをクリーンに保つ）からは外れるので採用は見送りました。

案 3: VS Code multi-root workspace

workspace.code-workspace を作って /var/www/html を追加フォルダとして登録する方法です。

{
  "folders": [
    { "path": "." },
    { "path": "/var/www/html" }
  ]
}

問題点:

• ファイルツリーに 同じ内容が 2 系統見えて紛らわしい
• git status は片方の workspace でしか機能しない（フルセットがある方は、git 管理外）

採用: Intelephense の includePaths を通す

観点	includePaths（採用）	stub	host 抽出	multi-root
実装まで読める	✅	❌	✅	✅
workspace ツリーに出ない	✅	✅	❌	❌
ホストを汚さない	✅	❌	❌	✅
設定の手間	設定 1 箇所	composer 導入	抽出スクリプト等	workspace ファイル
WP 更新追従	image 更新で自動	composer update	再抽出	image 更新で自動

includePaths 案が、今回の目的に一番適していました。

設定例の全体

実際に使っている .vscode/settings.json:

{
  // WordPress 本体のファイルがあるディレクトリを参照
  "intelephense.environment.includePaths": [
    "/var/www/html/wp-admin",
    "/var/www/html/wp-includes"
  ],

  // 索引から除外。uploads / cache は巨大になりがち、かつ、コードではないので除外。
  "intelephense.files.exclude": [
    "**/wordpress/wp-content/uploads/**",
    "**/wordpress/wp-content/cache/**",
    "**/wordpress/wp-content/upgrade/**",
    "/var/www/html/wp-content/uploads/**",
    "/var/www/html/wp-content/cache/**"
  ]
}

ホスト側パス (**/wordpress/wp-content/...) とコンテナ内パス (/var/www/html/wp-content/...) を両方書いているのは、ホスト側 VS Code で開いた場合と dev container で開いた場合のどちらでも索引対象から外れるようにするためです。

intelephense.files.exclude で uploads/ cache/ を除外しているのは、これらが巨大になりがちなうえに、コードは入っておらず不要なためです。

WordPress 以外への応用

サマリで触れた通り、同じ発想は 「ワークスペースには置きたくないが補完は効かせたいライブラリ群」 を扱う場面で広く有効です。

• PHP（WordPress 以外）: composer の vendor/ をコンテナ内に置き、intelephense.environment.includePaths でそのパスを渡す
• Python: python.analysis.extraPaths で site-packages や venv のパスを渡す

「補完エンジン（LSP）に追加索引パスを渡す」設定はエディタ・言語サーバごとに名前が違いますが、ホスト側のワークスペースをクリーンに保ちつつ dev container 内のソースを参照させる という形は応用が利きそうです。

まとめ

• 公式 WordPress Docker image + Dev Containers での環境構成では、WordPress 本体はコンテナの中だけにあり、ワークスペースには WordPress 本体がない状態となるが、Intelephense の設定でコンテナ内パスを include path として渡すことでエディタのサポート機能を利用できる
• ワークスペース内のファイルを最小限に抑え、ホスト環境をクリーンに保った状態でも、上記を実現することができる
• 設定は .vscode/settings.json のみ

WordPress テーマ・プラグイン開発を Docker でやっている方はぜひお試しください。もし、より良い方法をご存じでしたら教えていただけますと幸いです。