WSL2 + Docker の開発基盤と VS Code の Remote - WSL 利用準備ができている前提で、PHP 初期設定を最小構成でそろえます。
拡張、設定、動作確認までを 1 本で通し、最短で開発を始められる状態にします。
前提環境
次のいずれかの環境構築が完了している前提で進めます。
- Windows 11で始めるPHPローカル開発環境（WSL2 + Docker + PostgreSQL）
- Windows 11でPHP 8.3/8.4/8.5を使い分ける環境構築（WSL2 + mise + Docker Compose）
1. ゴールと非対象
この記事で到達する状態は次のとおりです。
- WSLワークスペースで、PHP開発に必要な拡張4つが有効になっている
.vscode/extensions.json/.vscode/settings.json/.editorconfigがそろっている- 補完・診断・Docker状態確認まで完了している
非対象は次のとおりです。
- Xdebug の運用詳細（ブレークポイント、
launch.json詳細） - フォーマッター運用（保存時自動整形やルール統一）
- CI連携、他IDE比較
本記事では xdebug.php-debug を導入しますが、ここでは導入確認までに限定します。
実運用は別記事で扱います。
2. 前提確認（Remote - WSLで開く）
まず、実行前提を確認します。 この時点で、Windows 側の Docker Desktop を起動しておいてください。
PowerShell で確認:
wsl -l -vPowerShell から WSL に入る:
wslWSL（Ubuntu）で確認:
code --version
docker version次に、WSL側の作業ディレクトリを開きます。
mkdir -p ~/projects/vscode-php-dev-setup-sample
cd ~/projects/vscode-php-dev-setup-sample
code .ポイント:
- Windows側フォルダではなく、WSL側（例:
~/projects）を開いてください。 - 前提確認で詰まった場合は、先に 8. よくある詰まりと次の一歩 を確認してください。
ここまでの動作確認
wsl -l -vで対象ディストリビューションがVERSION 2になっているcode --versionが表示されるdocker versionが表示されるcode .で Remote - WSL ウィンドウが開く
3. 推奨拡張4つを導入する
WSLターミナルで次を実行します。
code --install-extension を WSL ターミナルから実行すると、拡張は WSL 側の VS Code リモート環境に導入されます。
code --install-extension bmewburn.vscode-intelephense-client --force
code --install-extension xdebug.php-debug --force
code --install-extension editorconfig.editorconfig --force
code --install-extension ms-azuretools.vscode-docker --force導入後に確認:
code --list-extensions | grep -E "bmewburn.vscode-intelephense-client|xdebug.php-debug|editorconfig.editorconfig|ms-azuretools.vscode-docker"
その後、VS Code で Developer: Reload Window を1回実行します。
Ctrl + Shift + P でコマンドパレットを開き、Developer: Reload Window を選択してください。
ポイント:
xdebug.php-debugは本記事内で運用しません。- 後続のXdebug記事で再導入を避けるため、初期導入でそろえています。
ここまでの動作確認
code --list-extensionsの結果に4拡張IDが含まれている- Reload後も4拡張が有効なまま
4. extensions.json で推奨拡張を固定する
プロジェクトの推奨拡張を固定します。
mkdir -p .vscode
cat > .vscode/extensions.json <<'JSON'
{
"recommendations": [
"bmewburn.vscode-intelephense-client",
"xdebug.php-debug",
"editorconfig.editorconfig",
"ms-azuretools.vscode-docker"
]
}
JSON
ここまでの動作確認
cat .vscode/extensions.json- 4拡張IDが期待どおり並んでいる
5. settings.json の最小4キーを固定する
最小設定を保存します。
cat > .vscode/settings.json <<'JSON'
{
"editor.insertSpaces": true,
"editor.tabSize": 4,
"files.eol": "\n",
"editor.formatOnSave": false
}
JSON
ポイント:
editor.formatOnSaveはfalseに固定します（整形運用は別記事）。- インデント・改行の最終的な規約は6章の
.editorconfigで明示します。 settings.jsonはエディタの基本挙動、.editorconfigはプロジェクト規約として役割を分けています。editor.detectIndentationなどの運用詳細は、本記事では扱いません。
ここまでの動作確認
cat .vscode/settings.json- 4キーが期待どおり設定されている
6. .editorconfig で基本規約を固定する
規約ファイルを作成します。
cat > .editorconfig <<'CONF'
root = true
[*]
indent_style = space
indent_size = 4
end_of_line = lf
CONF
ここまでの動作確認
cat .editorconfigroot/indent_style/indent_size/end_of_lineが設定されている
7. 動作確認（補完・診断・Docker状態）
最小PHPファイルを用意して、補完と診断を確認します。
mkdir -p src
cat > src/index.php <<'PHP'
<?php
declare(strict_types=1);
$date = new DateTimeImmutable();
echo $date->format(DATE_ATOM) . PHP_EOL;
// 診断表示確認用（意図的に未定義）
echo $undefinedVariable;
PHP確認ポイント:
DateTimeImmutableのメソッド補完が表示される$undefinedVariableに未定義変数の診断が表示される- この診断は Intelephense の静的解析で、PHP実行環境がなくても表示される
code --list-extensionsで4拡張が継続表示される- Docker状態を確認できる
再確認コマンド（任意）:
code --list-extensions | grep -E "bmewburn.vscode-intelephense-client|xdebug.php-debug|editorconfig.editorconfig|ms-azuretools.vscode-docker"docker compose ps || docker ps --format "table {{.Names}}\t{{.Status}}"ここまでの動作確認
- 補完と診断がエディタ上で確認できる
- Docker拡張またはコマンドでコンテナ状態を確認できる
8. よくある詰まりと次の一歩
詰まりやすい症状と対処
| 症状 | 主な原因 | 対処 |
|---|---|---|
| 拡張が有効にならない | Windows側を開いている | WSLターミナルで cd ~/projects/... -> code . で再オープン |
code コマンドが見つからない | PATH未反映 / 起動直後 | ターミナルを開き直して code --version を再実行。改善しない場合は PowerShell で wsl --shutdown を実行した後、WSLを再起動して再確認 |
code --list-extensions に4拡張が出ない | 導入漏れ | 3章の4コマンドを再実行し、Developer: Reload Window 実施 |
| Docker拡張にコンテナが見えない | Docker Desktop未起動 / プロジェクトにcompose設定がない | docker version と docker compose ps（または docker ps）で状態確認 |
診断コマンド（再掲）:
which code
code --list-extensions
docker compose ps || docker ps --format "table {{.Names}}\t{{.Status}}"次の一歩
- フォーマッター運用（EditorConfig + PHP CS Fixer など）は別記事で扱う予定です（リンク準備中）。
- Xdebugのステップ実行は別記事で扱います（リンク準備中）。
- エディタ基盤を整えたあとに、最小CRUD記事へ進むと詰まりが減ります。
この記事で、VS CodeのPHP開発に必要な最小初期設定は完了です。