🐭
[2025年3月11更新] PHP開発者のためのCursor設定ガイド：共通設定・テスト・デバッグ・拡張機能まで

2025/03/05に公開
 筆者背景ずっとペチパー。たまにPythonなどの他言語も使用
PHPのエディタはPhpStormのみ使用。

 概要本記事は、PHPer向けのCursor（VSCodeフォーク）設定ガイドです。

備忘録としても活用できるよう、開発に役立つ設定のみをピックアップしています。

詳細な設定やオプションについては、適宜リンクを添付するので参考にしてください。

また、PhpStormに慣れ親しんでいる人がCursorに移行するのをスムーズにするための拡張機能なども含め紹介します。
⚠️ 注意

CursorはVsCodeのフォークであるため、本記事の設定はVSCodeにも転用可能です。

 前提Windows（WSL環境）
WSL（Ubuntu）環境でDockerを利用し、ローカル開発を行っている。
使用しているCursorのバージョンは以下のとおりです。
Version: 0.46.8
VSCode Version: 1.96.2
OS: Windows_NT x64
🚫 WSLやDockerのインストール手順は省略します。

 1. ワークスペース設定
 ワークスペースとして保存例えば、以下のようなディレクトリ構成を考えます。
parent-docker
 ├── src-directory
 ├── php-directory
このような構成でparent-dockerを開いた際に、src-directory内の検索がうまく機能しないことがあります。

その場合、ワークスペースとして保存 することで検索範囲を正しく設定できます。

 設定手順
[File] → [Save As Workspace] をクリックし、現在開いているフォルダをワークスペースとして保存

[File] → [Add Folder to Workspace] をクリックし、src-directoryを追加
これにより、「Ctrl + P」 でsrc-directory内のファイル検索が可能 になります。
📌 詳細記事：

VSCodeのワークスペースを設定する

 2. settings.json（エディタ設定）📌 設定ファイルの場所（Windows）

C:/Users/<ユーザー名>/AppData/Roaming/Cursor/User/settings.json

 主要な設定（推奨）{
    // セキュリティ関連: ワークスペース信頼やUNCホストなど
    // 不明な(未信頼の)ファイルをどう扱うか設定。ここでは「自動的に開く」。
    "security.workspace.trust.untrustedFiles": "open",
    // UNCパス(\\server\shareなど)でホストを許可する設定。WSL(Localhost)を許可する例
    "security.allowedUNCHosts": [
        "wsl.localhost"
    ],

    // ◆ Playwright関連: E2Eテストなどで利用する設定
    "playwright.reuseBrowser": true,
    // Playwright実行時にブラウザを使い回す(再起動を減らし、テスト実行高速化)。

    "playwright.showTrace": false,
    // Playwrightのテスト結果トレースを表示しないようにする。

    // ◆ エディター表示関連: ユニコードのハイライトやミニマップなど
    // コメント内にある非ASCII文字を強調表示しない設定
    "editor.unicodeHighlight.includeComments": false,
    // コードの右側に小さく全体を表示するミニマップを無効化
    "editor.minimap.enabled": false,

    // ◆ Cursor固有の設定例（AI補完など）
    // C++補完(推測)機能を、指定した言語モードでは無効にする
    "cursor.cpp.disabledLanguages": [
        "plaintext",
        "markdown",
        "scminput"
    ],
    // → AI補完候補を部分的に受け入れる(一部確定)といった操作を有効にするか
    "cursor.cpp.enablePartialAccepts": true,
    // PHP Composerとの連携機能をCursorで有効にする
    "cursor.composer.enabled": true,

    // ◆ PHPUnit関連: Docker上でPHPUnitを実行するための設定
    // PHPUnit実行前に付加されるコマンド。Dockerコンテナ内で実行するため"docker exec"を指定
    "phpunit.command": "docker exec docker_container_php",
    // PHPUnit本体へのパス。Dockerコンテナ内の場所を示している
    "phpunit.phpunit": "vendor/bin/phpunit",
    // ローカルパスとコンテナ内パスのマッピング。たとえば"/html"ディレクトリを"/var/www/cloud.ielove.jp"に対応付け
    "phpunit.paths": {
        "/html": "/var/www/my-cloud.example",
        "${workspaceFolder}": "/var/www"
    },
    // → Dockerコンテナ名。テスト実行で使用されるコンテナ
    "phpunit.docker.container": "docker_container_php",
    // Dockerイメージ名。指定したイメージからコンテナを起動する場合などに使用
    "phpunit.docker.image": "docker_container_php",

    // ◆ GitLens関連: GitログやBlame表示などを強化する拡張機能の設定
    // GitLensがステータスバーや行末などに表示するBlame情報のフォントサイズ
    "gitlens.currentLine.fontSize": 8,

    // ◆ エディター操作: マウスホイールズームやフォントサイズ
    // Ctrl(あるいはCmd)キーを押しながらマウスホイールを回すとフォントサイズが拡大縮小する設定
    "editor.mouseWheelZoom": true,
    // エディター全体のフォントサイズ
    "editor.fontSize": 10,

    // ◆ Intelephense関連: PHPの高度な補完と静的解析を行う拡張機能
    // 補完リストに表示する最大アイテム数
    "intelephense.completion.maxItems": 120,

    // ◆ ウィンドウ/リモート関連
    // VsCode上部(タイトルバー付近)に「コマンドセンター」を表示する新UIを有効にする
    "window.commandCenter": true,
    // WSLリモート関連のファイルをバックグラウンドでダウンロードしない設定
    "remote.WSL.downloadInBackground": false,
    // WSLリモートのデバッグログを有効にする(詳細なログ出力)
    "remote.WSL.debug": true,

    // ◆ Git関連
    // Gitリポジトリを自動フェッチし、リモートの更新を定期的に取得する
    "git.autofetch": true,

    // ◆ エディター入力補助: wordSeparators
    // ダブルクリック時に単語を分割する文字の定義。"$" を削除しているため$を含めて選択可能
    "editor.wordSeparators": "`~!@#%^&*()-=+[{]}\\|;:'\",.<>/?",

    // ◆ 検索エディター: 結果のフォーカスや行番号など
    // 「検索エディター」を使ったときに、検索実行後、結果の表示部にフォーカスを移す
    "search.searchEditor.focusResultsOnSearch": true,
    // 検索結果に行番号を表示する
    "search.showLineNumbers": true,

    // ◆ デバッグ: ブレークポイント設定
    // すべてのファイル種別でブレークポイントを許可する(通常は特定言語のみ可)
    "debug.allowBreakpointsEverywhere": true,

    // ◆ workbench.colorCustomizations: エディターやスクロールバーなどの色調整
    "workbench.colorCustomizations": {
        "editor.selectionBackground": "#585f619a",     // 選択したテキスト背景色
        "editor.selectionForeground": "#000000",       // 選択したテキスト文字色(通常不要)
        "editor.inactiveSelectionBackground": "#ffcc0080", // 非アクティブなエディターでの選択色
        "scrollbar.shadow": "#000000",                 // スクロールバーの影
        "scrollbarSlider.background": "#9099e7c9",     // スクロールバーの基本色
        "scrollbarSlider.hoverBackground": "#9099e79f", // マウスホバー時の色
        "scrollbarSlider.activeBackground": "#9099e7c9" // クリック/ドラッグ時の色
    }
}
この辺りは個人の好みに左右されますが、PHPに特化したIDEライクな操作を目指す際には、エラーや警告が見やすい配色に調整するのが良いでしょう。

 3. テスト関連設定
 PHPUNIT
PHPUnit拡張機能 をインストール

File>Preferences>VS Code Settingにて、Search settingsフォームで@ext:emallin.phpunitを入力すると、PHP Unit Configrationに移動
📌 設定例

Code Lens: "Enabled"
テストメソッドやクラスの上にRun TestやDebug Testのボタンが表示される


Docker:Container: "任意のコンテナ名"
Dockerコンテナ内でPHPUnitを実行する場合に使用


Docker:Image: "任意のコンテナ名"
Dockerイメージを使って一時的に PHPUnitを実行する場合に使用


 Xdebug（Docker環境向け）
XdebugをDockerのコンテナ環境にて利用するために、Dockerfileにて以下のようにパッケージをインストールしてください。
RUN apt-get update && apt-get install -y \
    #  XdebugをPECL（PHP Extension Community Library） 経由でインストール
    && pecl install xdebug \
    #  XdebugをPHPの拡張機能として有効化
    && docker-php-ext-enable xdebug \
    # Dockerイメージのサイズを削減し、コンテナの不要なキャッシュを減らす
    && rm -rf /var/lib/apt/lists/* 

 php.iniphp.iniでは以下のように設定
[XDebug]
; debug VSCodeなどのIDEでリモートデバッグが可能
; profile プロファイリング（実行時間・メモリ使用量の測定）
; trace 実行トレースを出力（関数の実行順などを記録）
; カンマ区切りで指定可能
xdebug.mode = debug,profile

; PHPスクリプトの実行時に自動的にXdebugを有効化するかを設定
xdebug.start_with_request = yes

; Xdebugのデバッグセッションを接続するホスト（IDE）を指定
; host.docker.internal は、Docker コンテナ内からホストマシン（WindowsやmacOS）を参照するための特殊なアドレス
; Docker 以外では 127.0.0.1 で OK
xdebug.client_host = host.docker.internal

; Xdebug3.xのデフォルトは`9003`ですが、Xdebug2.xの場合は 9000
xdebug.client_port = 9003

; Xdebugのログを出力するファイルのパスを指定
xdebug.log = /var/log/xdebug.log

; 0:無効, 1:エラー, 2:警告, 3:情報
xdebug.force_display_errors=0

; PHPのエラーメッセージを強制的に表示するかどうかを設定。0にすると、エラーが発生しても実行は続行
xdebug.break_on_error=0

; Warning（警告）で実行を停止するかどうかを設定。0にすると、警告が出ても停止しない。
xdebug.break_on_warning=0

; 例外（Exception）が発生したときに実行を停止するかを設定。0だと例外が発生しても停止しない。
xdebug.break_on_exception=0
📌 VSCodeのデバッグ設定（.vscode/launch.json）
{
    "version": "0.2.0", // VSCode Debug Adapter Protocolのバージョン
    "configurations": [
    {
        "name": "Listen for Xdebug", // VSCode の「デバッグと実行」メニューに表示される名称
        "type": "php", // デバッグ対象の言語（PHP） を指定
        "request": "launch", // デバッグの開始方法を指定。"launch" は、スクリプトをVSCode から直接起動してデバッグする場合に使用
        "port": 9003, // Xdebug がリモートデバッグ接続を待ち受けるポート番号。Xdebug3.x ではデフォルトのポートが9003
        "pathMappings": {
            // リモートサーバー上の PHP ファイルのパスと、ローカルのワークスペースのパスを対応付ける設定（左辺がリモートサーバー、つまりDocker環境におけるディレクトリパス）
            "/var/www/project-directory": "${workspaceFolder}/project-directory"
        },
        // デバッグ時にステップインしない（スキップする）ファイル を指定
        "skipFiles": [
            "**/project-directory/index.php",
            "**/App/Model/Func2.php"
        ],
        // 特定のPHPエラーを無視する設定
        "ignore": [
            "E_WARNING",
            "E_NOTICE",
            "E_DEPRECATED"
        ]
    }
  ]
}
📌 ポイント
Docker環境でXdebugを有効化
デバッグポート 9003 に設定
launch.json で pathMappings を正しく設定

 4. おすすめ拡張機能(Extensions)

拡張機能
説明


WSL
WindowsからWSL環境にリモート接続

PHP Intelephense
PHPのコード補完・静的解析
※@builtin phpをDisableにすること。詳細はこちら


PHP Debug
Xdebugを利用したデバッグ

PHPUnit
VSCode内でPHPUnitテスト実行

GitLens
Gitの履歴やBlameを表示

All-in-One PHP
この拡張機能をいれるだけで、IntelliSense（コード補完・シンタックス支援）、Debug（デバッグ機能）、Formatter（自動整形）、Code Lenses（コードレンズ）、Code Fixes（コード修正サジェスト）、Linting（構文チェック）、Refactoring（リファクタリング）、PHPUnit Tests（ユニットテスト支援）などが実現可能

MySQL Shell for VS Code
MySQLのGUIツール
左サイドバーの ▼ > MySQL Shell for VS Code アイコンをクリック

Copy Relative Path and Line Numbers
右クリックやショートカットで指定行の何行目＋ファイルパスをクリップボードコピーする



※dockerやcomposerをインストールして良いが、CUIでやりがちなので割愛。

 5. .cursorignore（インデックス対象の除外設定）CursorはAI補完のためにファイルを解析しますが、不要なファイルを除外するとパフォーマンスが向上します。
📌 設定例
# 不要なディレクトリ
node_modules/
vendor/
dist/

# ログファイルを除外
*.log
*.tmp

 6. Rules
 Privacy mode会社で使っている人ならなおさらここは enabled にしたほうが良いと思います。

 .cursorrules
ルートディレクトリに設置
サンプルあなたはPHP 8.4、MySQL 8.0、フロントエンド（HTML/CSS/JavaScript）に関する専門家です。
【PHP 8.4】

コードスタイルと構造:
厳密な型指定を使用し、null安全演算子・ユニオン型などの最新構文を活用する
簡潔で技術的な関数型コードを優先し、クラス設計が不要な場合は関数を活用する
コードの重複を避けるため、共通処理は関数もしくはトレイトに切り出す
命名は動作や状態を明示する形容詞/動詞の組み合わせを使用（例：isValid、hasPermission、fetchData）
ファイル構造：
ディレクトリを機能/用途別に整理（Controllers、Services、Models、Helpers、Views など）
エクスポート・インポート（autoload）をcomposer.json/autoloadで管理する
クラス名とファイル名をPSR-4規約に合わせる

パフォーマンス最適化:
遅延読み込み（autoload）を正しく設定し、必要なクラスのみ読み込む
キャッシュ（OPcache、アプリケーションキャッシュ）を有効活用する
ループ内でのDBアクセス回数を最小限に抑える（まとめて取得、コレクション操作など）
不要なファイル読込やレガシーコードを排除し、シンプルな依存構成を維持する
セキュリティ:
PDOのプリペアドステートメントを使用してSQLインジェクションを防止する
XSS対策として、HTMLエスケープやテンプレートエンジンのサニタイズ機能を使う
パスワードは password_hash / password_verify を用い安全にハッシュ化
エラーや例外メッセージには機密情報を含まない
【MySQL 8.0】

クエリとテーブル設計:
SQLインジェクション対策として、パラメータバインドやプリペアドステートメントを必ず使用する
SELECT * は避け、必要なカラムのみ明示的に指定する
テーブル・カラム名はスネークケースで統一し、役割がわかる命名を行う（例：user_profiles、order_items）
MySQL 8.0 で追加されたJSON型やCTE（WITH句）など、新しい機能も適切に活用する
必要に応じてインデックスを設定し、クエリのパフォーマンスを定期的に確認する
パフォーマンス最適化:
適切なインデックス設計に加え、冗長なJOINを避け、正規化とパフォーマンスのバランスを考慮
大量データのUPDATE/DELETEはトランザクションを活用し、段階的に行う（影響範囲を最小化）
クエリ実行計画（EXPLAIN）を適宜チェックし、遅いクエリを最適化する
【フロントエンド（HTML/CSS/JavaScript）】

コードスタイルと構造:
HTML5の構造化タグ（<header>、<main>、<section>、<footer>等）を正しく使用する
CSSはBEMやシンプルな命名規則を用いて可読性・再利用性を高める
JavaScriptはES6+構文を使用し、varの代わりにlet/constを利用する
コメントや命名により、変数・関数の意図を明確にする（例：isVisible、handleSubmit）
大規模なスクリプトはモジュール化（import/export）し、依存関係をわかりやすくする
パフォーマンス最適化:
不要なライブラリは読み込まず、必要最小限のスクリプトで構成する
CSSやJSの圧縮（Minify）、画像の圧縮と適切なフォーマット（WebPなど）を活用
レイジーロード（Intersection Observer APIなど）を使用して画像や重リソースを後読み込みする
HTTP/2 やキャッシュ制御を利用し、ページロードを高速化する
アクセシビリティ:
alt属性を含む画像やラベル設定を徹底し、スクリーンリーダー対応を意識する
コントラスト比を確保し、文字やUI要素を見やすくする
キーボードのみでも操作できるUI設計を心がける
セキュリティ:
フォーム入力をサーバ側でもバリデーションし、XSSを防ぐ
CookieにはHttpOnly, Secure属性を付与し、CSRFトークンを使用する
外部スクリプト（CDN 等）利用時はSRI (Subresource Integrity)を検討する

 User Rules
Open Cursor Settings (Ctrl + Shift + J) > Rules > User Rulesにて設定可能

ユーザー全体にまたがる・個人的な好みに基づいたルールや設定を定義
サンプルAlways respond in 日本語

 Project Rules
Open Cursor Settings (Ctrl + Shift + J) > Rules > Project Rulesにて設定可能

プロジェクト固有の構造やルールを定義
命名規則やスタイルガイドを設定したり、プロジェクト構造を設定すると、Cursorがファイルをスキャンする範囲や役割を理解しやすくなる。
以上が「PHP 開発者のための Cursor 設定ガイド：テスト・デバッグ・拡張機能まで」のまとめです。

 7. ショートカットPhpStormに慣れている人がCursorを使い始めると慣れていないことが多々あると思います。

以下、少しでもPhpStormライクに使えるようなTipsを記載します。

設定は、File > Preferences > Keyboard Shortcuts

 クラス名、メソッド名検索
Go to Symbol in Workspace のキーバインドを入力するとフォームに#が付きます。
この状態でクラス名を打てばクラス名での検索ができます。

settings.jsonだとworkbench.action.showAllSymbolsがそれに該当
Search欄に#で始まるとワークスペース内のシンボルを検索

※ファイル内のシンボル検索は@で始まる

 保存時に自動でフォーマットをかける
settings.json>"editor.formatOnSave": true

 8. 余談
 Cursorの WSL 接続WSL に接続できない場合、以下の手順で接続を確立 できます。
WSLが未接続の場合、エディタ上部に >< が表示

>< をクリックし、Connect to WSL using Distro… を選択
インストール済みの Ubuntu（WSL）ディストリビューション を選択
📌 WSL接続のスクリーンショット


 クラスやメソッドの検索会社で大きなプロジェクトを複数人で開発すると、自分が開発しようとしているメソッドが実はもうあるのではないかと探すときに便利です。

CursorChatをAskにして@Codebaseでほしいメソッドの概要を記載すれば見つかることがあります。
拡張機能	説明
WSL	WindowsからWSL環境にリモート接続
PHP Intelephense	PHPのコード補完・静的解析 ※`@builtin php`をDisableにすること。詳細はこちら
PHP Debug	Xdebugを利用したデバッグ
PHPUnit	VSCode内でPHPUnitテスト実行
GitLens	Gitの履歴やBlameを表示
All-in-One PHP	この拡張機能をいれるだけで、`IntelliSense（コード補完・シンタックス支援）`、`Debug（デバッグ機能）`、`Formatter（自動整形）`、`Code Lenses（コードレンズ）`、`Code Fixes（コード修正サジェスト）`、`Linting（構文チェック）`、`Refactoring（リファクタリング）`、`PHPUnit Tests（ユニットテスト支援）`などが実現可能
MySQL Shell for VS Code	MySQLのGUIツール左サイドバーの ▼ > MySQL Shell for VS Code アイコンをクリック
Copy Relative Path and Line Numbers	右クリックやショートカットで指定行の何行目＋ファイルパスをクリップボードコピーする
[2025年3月11更新] PHP開発者のためのCursor設定ガイド：共通設定・テスト・デバッグ・拡張機能まで

筆者背景

概要

前提

1. ワークスペース設定

ワークスペースとして保存

設定手順

2. `settings.json`（エディタ設定）

主要な設定（推奨）

3. テスト関連設定

PHPUNIT

Xdebug（Docker環境向け）

php.ini

4. おすすめ拡張機能(Extensions)

5. `.cursorignore`（インデックス対象の除外設定）

6. Rules

Privacy mode

`.cursorrules`

User Rules

Project Rules

7. ショートカット

クラス名、メソッド名検索

保存時に自動でフォーマットをかける

8. 余談

Cursorの WSL 接続

クラスやメソッドの検索

Discussion
