From 6fa5e8ab3b38ea2cebd9ab3a005dc7366e41313f Mon Sep 17 00:00:00 2001 From: Mykhailo Los Date: Tue, 21 Apr 2026 16:15:48 +0300 Subject: [PATCH 1/3] [MOOSE-190]: Add shared debug settings --- composer.json | 4 + dev/configs/.vscode/launch.json | 14 +++ .../inject-phpstorm-php-debug-workspace.php | 113 ++++++++++++++++++ docs/development-tools.md | 28 ++++- 4 files changed, 155 insertions(+), 4 deletions(-) create mode 100644 dev/configs/.vscode/launch.json create mode 100644 dev/scripts/inject-phpstorm-php-debug-workspace.php diff --git a/composer.json b/composer.json index c4aedf0c1..778cf6adc 100644 --- a/composer.json +++ b/composer.json @@ -24,6 +24,8 @@ "create-auth": "op inject -i auth.template.json -o auth.json", "create-local-configs": "php ./dev/scripts/create-local-configs.php", "install-wordpress": "./dev/scripts/install-wordpress.sh", + "phpstorm-workspace-php-debug": "php ./dev/scripts/inject-phpstorm-php-debug-workspace.php", + "sync-vscode-launch": "mkdir -p .vscode && cp ./dev/configs/.vscode/launch.json ./.vscode/launch.json", "phpcbf": "./vendor/bin/phpcbf -s", "phpcs": "./vendor/bin/phpcs", "phpstan": "./vendor/bin/phpstan analyse --memory-limit=-1", @@ -39,6 +41,8 @@ "create-auth": "Create or update the auth.json file for Composer via 1Password CLI.", "create-local-configs": "Creates local config files for the project.", "install-wordpress": "Runs the WP CLI command to download and install WordPress. To change the WordPress version, run `composer config extra.wordpress-version `.", + "phpstorm-workspace-php-debug": "Adds or refreshes PhpServers (path mappings) in .idea/workspace.xml for PhpStorm PHP debug. Prompts before replacing a different existing PhpServers block; use PHPSTORM_PHP_DEBUG_OVERWRITE=1 when stdin is not a TTY. Run manually when needed.", + "sync-vscode-launch": "Copies dev/configs/.vscode/launch.json to .vscode/ at the project root, creating .vscode if it does not exist.", "phpcs": "Run PHPCS on the project.", "phpcbf": "Run PHPCBF on the project.", "phpstan": "Run PHPStan on the project.", diff --git a/dev/configs/.vscode/launch.json b/dev/configs/.vscode/launch.json new file mode 100644 index 000000000..625702d82 --- /dev/null +++ b/dev/configs/.vscode/launch.json @@ -0,0 +1,14 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Listen for Xdebug", + "type": "php", + "request": "launch", + "port": 9003, + "pathMappings": { + "/app/": "${workspaceFolder}/" + } + } + ] +} diff --git a/dev/scripts/inject-phpstorm-php-debug-workspace.php b/dev/scripts/inject-phpstorm-php-debug-workspace.php new file mode 100644 index 000000000..dd26df598 --- /dev/null +++ b/dev/scripts/inject-phpstorm-php-debug-workspace.php @@ -0,0 +1,113 @@ + /app). + * + * Run manually: composer run phpstorm-workspace-php-debug + * + * If workspace.xml already contains a different PhpServers block, asks for + * confirmation before overwriting. Non-interactive runs must set: + * PHPSTORM_PHP_DEBUG_OVERWRITE=1 + */ + +$repo_root = dirname( __DIR__, 2 ); +$path = $repo_root . '/.idea/workspace.xml'; +$idea_dir = $repo_root . '/.idea'; + +$php_servers = <<<'XML' + + + + + + + + + +XML; + +$snippet_pattern = '/]*\bname\s*=\s*"PhpServers"[^>]*>.*?<\/component>/s'; + +$force_raw = getenv( 'PHPSTORM_PHP_DEBUG_OVERWRITE' ); +$force = in_array( + strtolower( trim( (string) $force_raw ) ), + [ '1', 'true', 'yes', 'y' ], + true +); + +/** + * @return bool True to proceed with overwrite. + */ +function confirm_overwrite( string $existing, bool $force ): bool { + if ( $force ) { + return true; + } + if ( ! stream_isatty( STDIN ) ) { + fwrite( + STDERR, + "Refusing to overwrite an existing PhpServers block without a TTY.\n" + . "Run this in an interactive terminal, or set PHPSTORM_PHP_DEBUG_OVERWRITE=1.\n" + ); + exit( 2 ); + } + + echo "Found an existing block in workspace.xml.\n"; + echo "Current block:\n\n"; + $preview = trim( $existing ); + if ( strlen( $preview ) > 1200 ) { + $preview = substr( $preview, 0, 1200 ) . "\n…"; + } + echo $preview . "\n\n"; + echo 'Replace it with the project default PhpServers configuration? [y/N]: '; + $answer = strtolower( trim( (string) fgets( STDIN ) ) ); + + return in_array( $answer, [ 'y', 'yes' ], true ); +} + +if ( ! is_dir( $idea_dir ) && ! mkdir( $idea_dir, 0775, true ) && ! is_dir( $idea_dir ) ) { + fwrite( STDERR, "Could not create directory: {$idea_dir}\n" ); + exit( 1 ); +} + +if ( ! is_file( $path ) ) { + $content = "\n" + . "\n" + . $php_servers . "\n" + . "\n"; + file_put_contents( $path, $content ); + echo "Created {$path}\n"; + exit( 0 ); +} + +$original = (string) file_get_contents( $path ); + +if ( preg_match( $snippet_pattern, $original, $match ) ) { + $existing = $match[0]; + if ( trim( $existing ) === trim( $php_servers ) ) { + echo "No changes needed (PhpServers already matches project default): {$path}\n"; + exit( 0 ); + } + if ( ! confirm_overwrite( $existing, $force ) ) { + echo "Skipped; workspace.xml was not modified.\n"; + exit( 0 ); + } + $updated = (string) preg_replace( $snippet_pattern, $php_servers, $original, 1 ); +} else { + $marker = ''; + $idx = strrpos( $original, $marker ); + if ( $idx === false ) { + fwrite( STDERR, "Could not find closing '{$marker}' in {$path}\n" ); + exit( 1 ); + } + $before = rtrim( substr( $original, 0, $idx ), "\n" ); + $after = substr( $original, $idx ); + $prefix = $before !== '' ? "\n" : ''; + $updated = $before . $prefix . $php_servers . "\n" . $after; +} + +if ( $updated !== $original ) { + file_put_contents( $path, $updated ); + echo "Updated {$path}\n"; +} else { + echo "No changes needed: {$path}\n"; +} diff --git a/docs/development-tools.md b/docs/development-tools.md index 0696c51e2..a57a02721 100644 --- a/docs/development-tools.md +++ b/docs/development-tools.md @@ -40,6 +40,25 @@ Xdebug **3** uses **port 9003** by default (not 9000). Configure your IDE to lis --- +## Composer commands for IDE debugging + +The repo ships two **optional** Composer scripts that copy or inject shared debug-related IDE settings. **Both can overwrite what you already have** in the paths below. If you customized those files or sections, back them up or merge your changes after running a script. + +### `composer run phpstorm-workspace-php-debug` + +Updates **only** **`.idea/workspace.xml`**, by adding or replacing the **PhpStorm** **PhpServers** block (path mappings such as project root → **`/app`**). If **PhpServers** already exists and differs from the project default, the script **asks for confirmation** before replacing it; in a non-interactive shell (no TTY), set **`PHPSTORM_PHP_DEBUG_OVERWRITE=1`** or the update is refused. Close PhpStorm first so it does not rewrite **`workspace.xml`** when the IDE exits. + +### `composer run sync-vscode-launch` + +Copies **`dev/configs/.vscode/launch.json`** to **`.vscode/launch.json`** at the project root and creates **`.vscode`** if it is missing. **Running this replaces the whole file** if **`.vscode/launch.json`** already exists. + +**Visual Studio Code** and **Cursor** need the **PHP Debug** extension by Xdebug (**extension id** **`xdebug.php-debug`**) as a **minimum** to use the Xdebug listen / launch definitions in that file—the editor cannot drive those configurations without it. Xdebug still runs inside **Lando**; the extension only connects the IDE to the debugger. + +* [PHP Debug — Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug) +* [PHP Debug — Open VSX](https://open-vsx.org/extension/xdebug/php-debug) (often used by Cursor and other VS Code–compatible editors) + +--- + ## PhpStorm Official reference: [Debug PHP with PhpStorm](https://www.jetbrains.com/help/phpstorm/debugging-php.html) and [Zero-configuration debugging](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html). @@ -60,7 +79,8 @@ PhpStorm includes PHP and Xdebug support; install PhpStorm from [JetBrains](http Start **Listen for PHP Debug Connections** (toolbar telephone icon, or **Run → Start Listening for PHP Debug Connections**). 4. **Server and path mappings** - **Settings → PHP → Servers**: add a server whose **host** and **port** match the URL you open in the browser (from `lando info`). Enable **Use path mappings** and map your project root to **`/app`**. + **Settings → PHP → Servers**: add a server whose **host** and **port** match the URL you open in the browser (from `lando info`). Enable **Use path mappings** and map your project root to **`/app`**. + Alternatively, from the project root you can run **`composer run phpstorm-workspace-php-debug`** to inject the team **PhpServers** snippet into **`.idea/workspace.xml`** (see [Composer commands for IDE debugging](#composer-commands-for-ide-debugging)—this can overwrite an existing **PhpServers** block). 5. **IDE key (if you use a browser extension)** **Settings → PHP → Debug → DBGp Proxy**: set the **IDE key** (for example `PHPSTORM`) and enter the same value in the browser extension so the session matches. @@ -79,13 +99,13 @@ PhpStorm includes PHP and Xdebug support; install PhpStorm from [JetBrains](http ### Install 1. Install [Visual Studio Code](https://code.visualstudio.com/). -2. Install the **PHP Debug** extension by Xdebug ([Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug)). Extension documentation: [vscode-php-debug](https://github.com/xdebug/vscode-php-debug). +2. Install the **PHP Debug** extension by Xdebug (**extension id** **`xdebug.php-debug`**). It is **required** if you use the repo’s **`launch.json`** Xdebug configurations ([Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug)). Extension documentation: [vscode-php-debug](https://github.com/xdebug/vscode-php-debug). Xdebug itself still runs only in the **Lando** container; the extension connects from VS Code to that debug session. ### Configure `launch.json` -Add a configuration that listens for Xdebug and maps paths. Example **Listen for Xdebug** setup (adjust **`pathMappings`** if your workspace root differs): +From the project root, **`composer run sync-vscode-launch`** copies **`dev/configs/.vscode/launch.json`** into **`.vscode/launch.json`** (see [Composer commands for IDE debugging](#composer-commands-for-ide-debugging)—**this overwrites** an existing **`.vscode/launch.json`**). Or add a configuration manually. Example **Listen for Xdebug** setup (adjust **`pathMappings`** if your workspace root differs): ```json { @@ -119,7 +139,7 @@ Lando-specific notes and examples: [Using Lando with VS Code](https://docs.lando ## Cursor -There is no separate Xdebug stack for Cursor. Cursor is a [VS Code–compatible editor](https://cursor.com/), so you use the **same** approach as in [Visual Studio Code](#visual-studio-code): install the **PHP Debug** extension ([Open VSX listing](https://open-vsx.org/extension/xdebug/php-debug), same extension id `xdebug.php-debug`), add the same **`launch.json`** listen configuration (port **9003**, `pathMappings` from **`/app`** to **`${workspaceFolder}`**), run **`lando xdebug-on`**, start the listener, then trigger a request from the browser. +There is no separate Xdebug stack for Cursor. Cursor is a [VS Code–compatible editor](https://cursor.com/), so you use the **same** approach as in [Visual Studio Code](#visual-studio-code): install the **PHP Debug** extension (**`xdebug.php-debug`**; [Open VSX listing](https://open-vsx.org/extension/xdebug/php-debug)), run **`composer run sync-vscode-launch`** if you want the shared **`.vscode/launch.json`** (overwrites an existing file—see [Composer commands for IDE debugging](#composer-commands-for-ide-debugging)), or add the same **`launch.json`** listen configuration (port **9003**, `pathMappings` from **`/app`** to **`${workspaceFolder}`**). Then run **`lando xdebug-on`**, start the listener, and trigger a request from the browser. Install extensions from Cursor’s **Extensions** view (Cursor may pull from its own marketplace or Open VSX depending on version). If an extension is missing from search, see [Cursor documentation](https://docs.cursor.com/) (including migration / troubleshooting for VS Code parity). From 107abf8cf1fd412441a2495168abe995116b72d6 Mon Sep 17 00:00:00 2001 From: Mykhailo Los Date: Tue, 21 Apr 2026 16:23:46 +0300 Subject: [PATCH 2/3] [MOOSE-190]: Add shared debug settings --- docs/development-tools.md | 34 ++++++++++------------------------ 1 file changed, 10 insertions(+), 24 deletions(-) diff --git a/docs/development-tools.md b/docs/development-tools.md index a57a02721..a1e33da82 100644 --- a/docs/development-tools.md +++ b/docs/development-tools.md @@ -40,25 +40,6 @@ Xdebug **3** uses **port 9003** by default (not 9000). Configure your IDE to lis --- -## Composer commands for IDE debugging - -The repo ships two **optional** Composer scripts that copy or inject shared debug-related IDE settings. **Both can overwrite what you already have** in the paths below. If you customized those files or sections, back them up or merge your changes after running a script. - -### `composer run phpstorm-workspace-php-debug` - -Updates **only** **`.idea/workspace.xml`**, by adding or replacing the **PhpStorm** **PhpServers** block (path mappings such as project root → **`/app`**). If **PhpServers** already exists and differs from the project default, the script **asks for confirmation** before replacing it; in a non-interactive shell (no TTY), set **`PHPSTORM_PHP_DEBUG_OVERWRITE=1`** or the update is refused. Close PhpStorm first so it does not rewrite **`workspace.xml`** when the IDE exits. - -### `composer run sync-vscode-launch` - -Copies **`dev/configs/.vscode/launch.json`** to **`.vscode/launch.json`** at the project root and creates **`.vscode`** if it is missing. **Running this replaces the whole file** if **`.vscode/launch.json`** already exists. - -**Visual Studio Code** and **Cursor** need the **PHP Debug** extension by Xdebug (**extension id** **`xdebug.php-debug`**) as a **minimum** to use the Xdebug listen / launch definitions in that file—the editor cannot drive those configurations without it. Xdebug still runs inside **Lando**; the extension only connects the IDE to the debugger. - -* [PHP Debug — Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug) -* [PHP Debug — Open VSX](https://open-vsx.org/extension/xdebug/php-debug) (often used by Cursor and other VS Code–compatible editors) - ---- - ## PhpStorm Official reference: [Debug PHP with PhpStorm](https://www.jetbrains.com/help/phpstorm/debugging-php.html) and [Zero-configuration debugging](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging.html). @@ -69,6 +50,10 @@ PhpStorm includes PHP and Xdebug support; install PhpStorm from [JetBrains](http ### Configure +You can configure everything **manually** in PhpStorm (steps below), **or** from the project root run **`composer run phpstorm-workspace-php-debug`** to inject the team’s **basic PhpServers** block (project root → **`/app`**) into **`.idea/workspace.xml`**. You still need to set port **9003**, start listening, and match host/port to your Lando URL—those are not written by the script. Close PhpStorm before running the Composer command so it does not overwrite **`workspace.xml`** on exit. + +If **PhpServers** already exists and differs from the project default, the script **prompts** before replacing it; in a non-interactive shell set **`PHPSTORM_PHP_DEBUG_OVERWRITE=1`**. Back up or merge **`.idea/workspace.xml`** if you rely on custom **PhpServers** settings. + 1. **PHP interpreter (optional check)** **Settings → PHP**. You can use a local PHP or skip remote CLI if you only debug web requests via Lando. @@ -79,8 +64,7 @@ PhpStorm includes PHP and Xdebug support; install PhpStorm from [JetBrains](http Start **Listen for PHP Debug Connections** (toolbar telephone icon, or **Run → Start Listening for PHP Debug Connections**). 4. **Server and path mappings** - **Settings → PHP → Servers**: add a server whose **host** and **port** match the URL you open in the browser (from `lando info`). Enable **Use path mappings** and map your project root to **`/app`**. - Alternatively, from the project root you can run **`composer run phpstorm-workspace-php-debug`** to inject the team **PhpServers** snippet into **`.idea/workspace.xml`** (see [Composer commands for IDE debugging](#composer-commands-for-ide-debugging)—this can overwrite an existing **PhpServers** block). + **Settings → PHP → Servers**: add a server whose **host** and **port** match the URL you open in the browser (from `lando info`). Enable **Use path mappings** and map your project root to **`/app`**, **or** use **`composer run phpstorm-workspace-php-debug`** as described above instead of entering **PhpServers** by hand. 5. **IDE key (if you use a browser extension)** **Settings → PHP → Debug → DBGp Proxy**: set the **IDE key** (for example `PHPSTORM`) and enter the same value in the browser extension so the session matches. @@ -99,13 +83,15 @@ PhpStorm includes PHP and Xdebug support; install PhpStorm from [JetBrains](http ### Install 1. Install [Visual Studio Code](https://code.visualstudio.com/). -2. Install the **PHP Debug** extension by Xdebug (**extension id** **`xdebug.php-debug`**). It is **required** if you use the repo’s **`launch.json`** Xdebug configurations ([Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug)). Extension documentation: [vscode-php-debug](https://github.com/xdebug/vscode-php-debug). +2. Install the **PHP Debug** extension by Xdebug (**extension id** **`xdebug.php-debug`**). It is **required** to use the Xdebug listen / launch definitions in **`launch.json`** ([Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug)). Extension documentation: [vscode-php-debug](https://github.com/xdebug/vscode-php-debug). Xdebug itself still runs only in the **Lando** container; the extension connects from VS Code to that debug session. ### Configure `launch.json` -From the project root, **`composer run sync-vscode-launch`** copies **`dev/configs/.vscode/launch.json`** into **`.vscode/launch.json`** (see [Composer commands for IDE debugging](#composer-commands-for-ide-debugging)—**this overwrites** an existing **`.vscode/launch.json`**). Or add a configuration manually. Example **Listen for Xdebug** setup (adjust **`pathMappings`** if your workspace root differs): +You can maintain `.vscode/launch.json` entirely by hand, **or** from the project root run **`composer run sync-vscode-launch`** to copy **`dev/configs/.vscode/launch.json`** into **`.vscode/launch.json`** (creates **`.vscode`** if needed). That gives you the repo’s **basic** listen / path-mapping setup in one step. **Running the command replaces the whole file** if **`.vscode/launch.json`** already exists—back it up first if you have custom configurations. + +If you prefer to edit manually, use something like the following **Listen for Xdebug** example (adjust **`pathMappings`** if your workspace root differs): ```json { @@ -139,7 +125,7 @@ Lando-specific notes and examples: [Using Lando with VS Code](https://docs.lando ## Cursor -There is no separate Xdebug stack for Cursor. Cursor is a [VS Code–compatible editor](https://cursor.com/), so you use the **same** approach as in [Visual Studio Code](#visual-studio-code): install the **PHP Debug** extension (**`xdebug.php-debug`**; [Open VSX listing](https://open-vsx.org/extension/xdebug/php-debug)), run **`composer run sync-vscode-launch`** if you want the shared **`.vscode/launch.json`** (overwrites an existing file—see [Composer commands for IDE debugging](#composer-commands-for-ide-debugging)), or add the same **`launch.json`** listen configuration (port **9003**, `pathMappings` from **`/app`** to **`${workspaceFolder}`**). Then run **`lando xdebug-on`**, start the listener, and trigger a request from the browser. +There is no separate Xdebug stack for Cursor. Cursor is a [VS Code–compatible editor](https://cursor.com/), so you follow the **same** model as [Visual Studio Code](#visual-studio-code): install the **PHP Debug** extension (**`xdebug.php-debug`**; [Open VSX listing](https://open-vsx.org/extension/xdebug/php-debug)), then either **manually** add the **`launch.json`** listen configuration (port **9003**, `pathMappings` from **`/app`** to **`${workspaceFolder}`**) **or** run **`composer run sync-vscode-launch`** from the project root to copy the repo’s **`launch.json`** into **`.vscode/`** (same overwrite warning as in the VS Code section). Then run **`lando xdebug-on`**, start the listener, and trigger a request from the browser. Install extensions from Cursor’s **Extensions** view (Cursor may pull from its own marketplace or Open VSX depending on version). If an extension is missing from search, see [Cursor documentation](https://docs.cursor.com/) (including migration / troubleshooting for VS Code parity). From 180f969cfaf9161d56e5b9953218957284866346 Mon Sep 17 00:00:00 2001 From: Mykhailo Los Date: Tue, 5 May 2026 17:13:07 +0300 Subject: [PATCH 3/3] [MOOSE-190]: Address code review notices --- composer.json | 2 - .../inject-phpstorm-php-debug-workspace.php | 113 ------------------ docs/development-tools.md | 6 +- 3 files changed, 1 insertion(+), 120 deletions(-) delete mode 100644 dev/scripts/inject-phpstorm-php-debug-workspace.php diff --git a/composer.json b/composer.json index 778cf6adc..1b38cfd40 100644 --- a/composer.json +++ b/composer.json @@ -24,7 +24,6 @@ "create-auth": "op inject -i auth.template.json -o auth.json", "create-local-configs": "php ./dev/scripts/create-local-configs.php", "install-wordpress": "./dev/scripts/install-wordpress.sh", - "phpstorm-workspace-php-debug": "php ./dev/scripts/inject-phpstorm-php-debug-workspace.php", "sync-vscode-launch": "mkdir -p .vscode && cp ./dev/configs/.vscode/launch.json ./.vscode/launch.json", "phpcbf": "./vendor/bin/phpcbf -s", "phpcs": "./vendor/bin/phpcs", @@ -41,7 +40,6 @@ "create-auth": "Create or update the auth.json file for Composer via 1Password CLI.", "create-local-configs": "Creates local config files for the project.", "install-wordpress": "Runs the WP CLI command to download and install WordPress. To change the WordPress version, run `composer config extra.wordpress-version `.", - "phpstorm-workspace-php-debug": "Adds or refreshes PhpServers (path mappings) in .idea/workspace.xml for PhpStorm PHP debug. Prompts before replacing a different existing PhpServers block; use PHPSTORM_PHP_DEBUG_OVERWRITE=1 when stdin is not a TTY. Run manually when needed.", "sync-vscode-launch": "Copies dev/configs/.vscode/launch.json to .vscode/ at the project root, creating .vscode if it does not exist.", "phpcs": "Run PHPCS on the project.", "phpcbf": "Run PHPCBF on the project.", diff --git a/dev/scripts/inject-phpstorm-php-debug-workspace.php b/dev/scripts/inject-phpstorm-php-debug-workspace.php deleted file mode 100644 index dd26df598..000000000 --- a/dev/scripts/inject-phpstorm-php-debug-workspace.php +++ /dev/null @@ -1,113 +0,0 @@ - /app). - * - * Run manually: composer run phpstorm-workspace-php-debug - * - * If workspace.xml already contains a different PhpServers block, asks for - * confirmation before overwriting. Non-interactive runs must set: - * PHPSTORM_PHP_DEBUG_OVERWRITE=1 - */ - -$repo_root = dirname( __DIR__, 2 ); -$path = $repo_root . '/.idea/workspace.xml'; -$idea_dir = $repo_root . '/.idea'; - -$php_servers = <<<'XML' - - - - - - - - - -XML; - -$snippet_pattern = '/]*\bname\s*=\s*"PhpServers"[^>]*>.*?<\/component>/s'; - -$force_raw = getenv( 'PHPSTORM_PHP_DEBUG_OVERWRITE' ); -$force = in_array( - strtolower( trim( (string) $force_raw ) ), - [ '1', 'true', 'yes', 'y' ], - true -); - -/** - * @return bool True to proceed with overwrite. - */ -function confirm_overwrite( string $existing, bool $force ): bool { - if ( $force ) { - return true; - } - if ( ! stream_isatty( STDIN ) ) { - fwrite( - STDERR, - "Refusing to overwrite an existing PhpServers block without a TTY.\n" - . "Run this in an interactive terminal, or set PHPSTORM_PHP_DEBUG_OVERWRITE=1.\n" - ); - exit( 2 ); - } - - echo "Found an existing block in workspace.xml.\n"; - echo "Current block:\n\n"; - $preview = trim( $existing ); - if ( strlen( $preview ) > 1200 ) { - $preview = substr( $preview, 0, 1200 ) . "\n…"; - } - echo $preview . "\n\n"; - echo 'Replace it with the project default PhpServers configuration? [y/N]: '; - $answer = strtolower( trim( (string) fgets( STDIN ) ) ); - - return in_array( $answer, [ 'y', 'yes' ], true ); -} - -if ( ! is_dir( $idea_dir ) && ! mkdir( $idea_dir, 0775, true ) && ! is_dir( $idea_dir ) ) { - fwrite( STDERR, "Could not create directory: {$idea_dir}\n" ); - exit( 1 ); -} - -if ( ! is_file( $path ) ) { - $content = "\n" - . "\n" - . $php_servers . "\n" - . "\n"; - file_put_contents( $path, $content ); - echo "Created {$path}\n"; - exit( 0 ); -} - -$original = (string) file_get_contents( $path ); - -if ( preg_match( $snippet_pattern, $original, $match ) ) { - $existing = $match[0]; - if ( trim( $existing ) === trim( $php_servers ) ) { - echo "No changes needed (PhpServers already matches project default): {$path}\n"; - exit( 0 ); - } - if ( ! confirm_overwrite( $existing, $force ) ) { - echo "Skipped; workspace.xml was not modified.\n"; - exit( 0 ); - } - $updated = (string) preg_replace( $snippet_pattern, $php_servers, $original, 1 ); -} else { - $marker = ''; - $idx = strrpos( $original, $marker ); - if ( $idx === false ) { - fwrite( STDERR, "Could not find closing '{$marker}' in {$path}\n" ); - exit( 1 ); - } - $before = rtrim( substr( $original, 0, $idx ), "\n" ); - $after = substr( $original, $idx ); - $prefix = $before !== '' ? "\n" : ''; - $updated = $before . $prefix . $php_servers . "\n" . $after; -} - -if ( $updated !== $original ) { - file_put_contents( $path, $updated ); - echo "Updated {$path}\n"; -} else { - echo "No changes needed: {$path}\n"; -} diff --git a/docs/development-tools.md b/docs/development-tools.md index a1e33da82..01337dbfa 100644 --- a/docs/development-tools.md +++ b/docs/development-tools.md @@ -50,10 +50,6 @@ PhpStorm includes PHP and Xdebug support; install PhpStorm from [JetBrains](http ### Configure -You can configure everything **manually** in PhpStorm (steps below), **or** from the project root run **`composer run phpstorm-workspace-php-debug`** to inject the team’s **basic PhpServers** block (project root → **`/app`**) into **`.idea/workspace.xml`**. You still need to set port **9003**, start listening, and match host/port to your Lando URL—those are not written by the script. Close PhpStorm before running the Composer command so it does not overwrite **`workspace.xml`** on exit. - -If **PhpServers** already exists and differs from the project default, the script **prompts** before replacing it; in a non-interactive shell set **`PHPSTORM_PHP_DEBUG_OVERWRITE=1`**. Back up or merge **`.idea/workspace.xml`** if you rely on custom **PhpServers** settings. - 1. **PHP interpreter (optional check)** **Settings → PHP**. You can use a local PHP or skip remote CLI if you only debug web requests via Lando. @@ -64,7 +60,7 @@ If **PhpServers** already exists and differs from the project default, the scrip Start **Listen for PHP Debug Connections** (toolbar telephone icon, or **Run → Start Listening for PHP Debug Connections**). 4. **Server and path mappings** - **Settings → PHP → Servers**: add a server whose **host** and **port** match the URL you open in the browser (from `lando info`). Enable **Use path mappings** and map your project root to **`/app`**, **or** use **`composer run phpstorm-workspace-php-debug`** as described above instead of entering **PhpServers** by hand. + **Settings → PHP → Servers**: add a server whose **host** and **port** match the URL you open in the browser (from `lando info`). Enable **Use path mappings** and map your **local project root** (repository root) to **`/app`** (the path inside the Lando container). PhpStorm stores **PhpServers** data inside **`.idea/workspace.xml`** (workspace-local settings). 5. **IDE key (if you use a browser extension)** **Settings → PHP → Debug → DBGp Proxy**: set the **IDE key** (for example `PHPSTORM`) and enter the same value in the browser extension so the session matches.