php-debugbar · omartins365 · Jul 31, 2025 · Jul 31, 2025 · Aug 9, 2025 · Aug 11, 2025
diff --git a/docs/vscode_wsl_links.md b/docs/vscode_wsl_links.md
@@ -0,0 +1,35 @@
+# VSCode WSL Remote Xdebug Link Support
+
+This package now supports generating Xdebug file links for VS Code running in WSL (Windows Subsystem for Linux) via the `vscode-wsl` editor type.
+
+## Prerequisites
+
+- Visual Studio Code installed on Windows
+- [WSL extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) for VS Code
+- WSL (e.g., Ubuntu) set up on your system
+
+## Usage
+
+Set the editor link template to `vscode-wsl`:
+
+```php
+// usage
+$collector->setEditorLinkTemplate('vscode-wsl');
+```
+
+You can configure the WSL distribution name (e.g., `Ubuntu`) using:
+
+- The `DEBUGBAR_WSL_NAME` environment variable
+- The `setWslName()` method
+
+If not set, it defaults to `Ubuntu`.
+
+## Example Link
+
+The generated link will look like:
+
+```
+vscode://vscode-remote/wsl+Ubuntu/path/to/file.php:1
+```
+
+Clicking this link in your browser on Windows will open the file in VS Code inside your WSL environment.
diff --git a/src/DebugBar/DataFormatter/HasXdebugLinks.php b/src/DebugBar/DataFormatter/HasXdebugLinks.php
@@ -17,6 +17,34 @@ trait HasXdebugLinks
     protected $xdebugLinkTemplate = '';
     protected $xdebugShouldUseAjax = false;
     protected $xdebugReplacements = array();
+    protected $wslName = null;
+    /**
+     * Set the WSL distribution name for vscode-wsl links.
+     *
+     * @param string|null $wslName
+     */
+    public function setWslName($wslName)
+    {
+        $this->wslName = $wslName;
+    }
+
+    /**
+     * Get the WSL distribution name, from property, env, or default.
+     *
+     * @return string
+     */
+    public function getWslName()
+    {
+        if ($this->wslName) {
+            return $this->wslName;
+        }
+        $env = getenv('DEBUGBAR_WSL_NAME');
+        if ($env) {
+            return $env;
+        }
+        // Optionally, set a default here, e.g. 'Ubuntu'
+        return 'Ubuntu';
+    }
 
     /**
      * Shorten the file path by removing the xdebug path replacements
@@ -72,10 +100,16 @@ public function getXdebugLink($file, $line = null)
             }
         }
 
-        $url = strtr($this->getXdebugLinkTemplate(), [
+        $template = $this->getXdebugLinkTemplate();
+        $replacements = [
             '%f' => rawurlencode(str_replace('\\', '/', $file)),
             '%l' => rawurlencode((string) $line ?: 1),
-        ]);
+        ];
+        // Add %w for WSL name if needed
+        if (strpos($template, '%w') !== false) {
+            $replacements['%w'] = rawurlencode($this->getWslName());
+        }
+        $url = strtr($template, $replacements);
         if ($url) {
             return [
                 'url' => $url,
@@ -119,6 +153,7 @@ public function setEditorLinkTemplate($editor)
             'vscode-insiders' => 'vscode-insiders://file/%f:%l',
             'vscode-remote' => 'vscode://vscode-remote/%f:%l',
             'vscode-insiders-remote' => 'vscode-insiders://vscode-remote/%f:%l',
+            'vscode-wsl' => 'vscode://vscode-remote/wsl+%w/%f:%l',
             'vscodium' => 'vscodium://file/%f:%l',
             'nova' => 'nova://open?path=%f&line=%l',
             'xdebug' => 'xdebug://%f@%l',

diff --git a/tests/DebugBar/Tests/HasXdebugLinksTest.php b/tests/DebugBar/Tests/HasXdebugLinksTest.php
@@ -0,0 +1,46 @@
+<?php
+
+namespace DebugBar\Tests;
+
+use PHPUnit\Framework\TestCase;
+use DebugBar\DataFormatter\HasXdebugLinks;
+
+class HasXdebugLinksTest extends TestCase
+{
+    use HasXdebugLinks;
+
+    public function testVscodeWslLinkGeneration()
+    {
+        $this->setEditorLinkTemplate('vscode-wsl');
+        $this->setWslName('CustomWSL');
+        $file = '/var/www/html/index.php';
+        $line = 42;
+        $link = $this->getXdebugLink($file, $line);
+        $this->assertStringContainsString('vscode://vscode-remote/wsl+CustomWSL', $link['url']);
+        $this->assertStringContainsString('index.php:42', urldecode($link['url']));
+    }
+
+    public function testVscodeWslLinkGenerationWithDefaultWslName()
+    {
+        $this->setEditorLinkTemplate('vscode-wsl');
+        // Do not set WSL name, should default to 'Ubuntu'
+        $file = '/var/www/html/test.php';
+        $line = 5;
+        $link = $this->getXdebugLink($file, $line);
+        $this->assertStringContainsString('vscode://vscode-remote/wsl+Ubuntu', $link['url']);
+        $this->assertStringContainsString('test.php:5', urldecode($link['url']));
+    }
+
+    public function testVscodeWslLinkGenerationWithEnvVar()
+    {
+        $this->setEditorLinkTemplate('vscode-wsl');
+        putenv('DEBUGBAR_WSL_NAME=EnvWSL');
+        // Do not set WSL name via setter, should use env var
+        $file = '/var/www/html/env.php';
+        $line = 7;
+        $link = $this->getXdebugLink($file, $line);
+        $this->assertStringContainsString('vscode://vscode-remote/wsl+EnvWSL', $link['url']);
+        $this->assertStringContainsString('env.php:7', urldecode($link['url']));
+        putenv('DEBUGBAR_WSL_NAME'); // Clean up
+    }
+}