Skip to main content

Enable phpstorm:// protocol on Windows 10 & WSL2

· 3 min read
Stephan Hochdörfer

A few tools, e.g. PHPStan Pro make use of the phpstorm:// protocol to be able to open files directly from your console with a click of a button.

While PhpStorm "understands" the phpstorm:// links and can open the respective files, I had to enable the functionality in Windows and also make sure that PhpStorm on Windows knows how to resolve the path in my WSL2 instance.

First, I installed the Jetbrains Toolbox app and used that to install PhpStorm. This seems to help later to open the file in an existing PhpStorm instance and not open a new PhpStorm instance for every file. The latter happened to me when using the standalone PhpStorm installer.

To make Windows aware of the phpstorm:// protocol, we need to configure it in the Windows registry. Luckily, I found a GitHub repo with a patch for the Windows registry as well as a Windows Script Host script to launch PhpStorm with the required information.

After cloning the repo on Windows, the sample Windows Script Host script needed a bit of configuration:

var settings = {
// Set to 'true' (without quotes) if run on Windows 64bit. Set to 'false' (without quotes) otherwise.
x64: true,

// Set to disk letter, where PhpStorm was installed to (e.g. C:)
disk_letter: 'C:',

// Set to folder name, where PhpStorm was installed to (e.g. 'PhpStorm')
folder_name: '',

// Set to window title (only text after dash sign), that you see, when switching to running PhpStorm instance
window_title: '',

// In case your file is mapped via a network share and paths do not match.
// eg. /var/www will can replaced with Y:/
projects_basepath: '/home/myuser',
projects_path_alias: '\\\\wsl$\\Ubuntu-22.04/\\home/myuser',

// PhpStorm directory name in Toolbox directory
// eg. for C:\Users\%username%\AppData\Local\JetBrains\Toolbox\apps\PhpStorm\ch-1 use 'ch-1'
toolbox_update_channel_dir: 'ch-0'


Since having JetBrains Toolbox installed, I was able to set window_title to an empty string because the Toolbox itself will figure out which PhpStorm instance to launch. But I need to configure the toolbox_update_channel_dir according to my local setup.

Since my development tools in my WSL2 instance only know about their local paths and Windows needs the \\wsl$\Ubuntu-22.04 prefix to understand which WSL2 instance is meant, it was needed to configure both the projects_basepath as well as the projects_path_alias. The latter was a bit tricky to configure due to the backslash escaping needed. After a few tries, I figured out what the path needs to look like.

To test if the script is working, I manually invoked the script the same way Windows would do it when clicking on a link:

wscript "run_editor.js" "phpstorm://open?file=%2Fhome%2Fmyuser%2FWorkspace%2Ftest%2Fsrc%2Fdemo.php&line=1" //E:JScript

Once everything was working as expected, I executed the registry script to register the phpstorm:// protocol in Windows and everything is working fine now.