You need to already have a Vagrant Box up and running. That is the prerequisite for this tutorial. This looks like more work than it really is, and once you fuddle through it, subsequent set-ups will come easy. This is how I set things up:
From PHPStorm (I’m using version 8 for this), open your local projects folder. As an example (I’m on a mac, so adjust as necessary) /Users/nsardo/Desktop/civicprojects/vagrant_busdec/busdec/public_html.
Once the project is opened in PHPStorm, open “preferences”. When the dialog open’s, click the disclosure triangle to open “Languages & Frameworks”, and click on “PHP”. Disregard the items under include path in my picture, they may not apply to you, but I will address them.
To the right of the drop down for ‘Interpreter’ is a button with three dots. This allows you to add the remote PHP interpreter from your vagrant box. Click it. An ‘Interpreters’ dialog will open. In the upper left you’ll see a plus, minus, and what looks like a couple documents. Click the ‘plus’ icon (to add a new interpreter):
A ‘Configure Remote PHP Interpreter’ dialog will open. Select the ‘Vagrant’ radio button. Next, either enter the path to your projects Vagrant folder, or use the button with three dots to the right of ‘Vagrant Instance Folder’ (the folder that has your Vagrant script– I then place the project web root project folder within this folder), and select it that way. Still in the dialog, you’ll see ‘PHP interpreter path’. You’ll need to enter the path on the running Vagrant Box of the php interpreter. In my case, it’s located at /usr/bin/php (on the running Vagrant box. Click ‘OK’ and name this interpreter instance.
Click on the ‘Test connection…’ button, to allow PHPStorm to sync up with the remote PHP Interpreter. If you also have XDebug set up on the Vagrant Box, PHPStorm will find it. Finally, Name this Interpreter in the ‘Interpreters’ Dialog.
After closing this box, my final ‘Interpreters’ Dialog looks like this:
This returns us to the ‘Languages & Frameworks > PHP’ dialog. At the top for PHP Language Level, I reset mine to 5.3 from the drop down (as that’s the version of PHP on the specific Vagrant Box I’m using).
Now an explanation of the include path: For my Vagrant box, Pear and other includable classes are located at /usr/share/php and /usr/share/pear. I also add the current directory. The way to set these up is in the bottom of the dialog, clicking the ‘plus’ button, and then adding the path.
Next, click the disclosure triangle at the side of PHP:
This exposes the ‘Servers’ item. Click the ‘plus’ icon, to add a new server:
Give it a name for your reference, and enter either the IP address, or host name for your running Vagrant Box. If you need to use a port other than 80, enter it. If you’re making use of a debugger, select it from the drop down. Next, click the ‘Validate remote environment’.
Now click the ‘Validate remote environment’. This brings up a dialog by the same name. In the drop down under ‘Deployment server’, select the name of the server you just created. In my case, this is ‘busdec’. Enter the path to your project (or use the three-dot button, and navigate to it and select).
Next, just to the right of the ‘Deployment server’ drop down is a three-dot button. Click it. This will bring up the ‘Deployment’ dialog:
Under the ‘Connection’ tab, select ‘In place’ from the drop down to the right of ‘Type’, then enter the root url of your vagrant box. Next click the ‘Mappings’ tab:
This is VERY IMPORTANT: as per jetbrains.com tech support– if the files are not mapped from your local machine to your Vagrant Box, debugging will break, unable to find files. The solution I took was to copy over the entire hierarchy of directories on the Vagrant Box, i.e. /usr/share/php into my local project folder. Then mapping to it.
Mapping is quite simple. You click the lower left ‘plus’ button to add a path. Under ‘Local Path’, select your project root (i.e the folder apache, nginx, etc. will serve). In my case, the local project root is /Users/nsardo/Desktop/civicprojects/vagrant_busdec/busdec/public_html/ This maps to the Web Path ‘/’. Then, in the case of the includes (on the Vagrant box) that I copied into my project, their local path is: /Users/nsardo/Desktop/civicprojects/vagrant_busdec/usr/share/php/ This maps to /usr/share/php/ on the Vagrant Box. Having done this, we’re ready to validate everything in PHPStorm. Click the ‘Validate’ button, and if everything was successful, you should see something along the lines of:
With all this done, click ‘apply’ at the bottom of the ‘Preferences > Languages & Frameworks > PHP > Servers, then OK.
Finally, in the main project window of PHPStorm, just to the right of the ‘play’ button in the upper right (here, I have already selected busdec, as shown) and select ‘Edit Configurations…’:
Under the ‘Defaults’ menu along the right, open the disclosure triangle if it is not already. Click on the ‘PHP Remote Debug’ item, and then in the above left, click on the ‘plus’ icon. This will create a new Run/Debug configuration. Name it (in my case, I named it ‘busdecv’. In the ‘Servers’ drop down, select the server you previously created (in my case, ‘busdec’). Enter whatever Ide key(session id) you wish to use. I set up XDebug to use ‘vagrant’, so that is what I used. In the bottom right, click ‘apply’, and then ‘OK’.
The final thing to do is click on the ‘Start Listening for Debug connections’ button, which is just to the left of the ‘VCS’ with a down pointing arrow under it, or put another way: starting at the magnifying glass icon in the upper right of the main PHPStorm window, counting the magnifying glass as one, count over 6 to the left.
You should now have everything set up. Chrome (and I’m pretty sure Firefox, maybe other’s) have an XDebug extension for setting a page within the browser. PHPStorm also have some bookmarklet’s you can add as well.