Set-up PHPStorm with Remote Debugging for Vagrant Box


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.

Set Remote PHP in PHPStorm
Set Remote PHP in PHPStorm

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):

Set up Vagrant PHP Interpreter
Set up Vagrant PHP 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.

Setting up the Vagrant PHP Interpreter
Setting up the Vagrant PHP Interpreter

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.

Test Remote PHP Connection
Test Remote PHP Connection

After closing this box, my final ‘Interpreters’ Dialog looks like this:

Final PHP Interpreters Dialog
Final PHP Interpreters Dialog

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:

Clicking PHP disclosure triangle
Clicking PHP disclosure triangle

This exposes the ‘Servers’ item. Click the ‘plus’ icon, to add a new server:

Adding a new Server
Adding 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’.

Completed Server Dialog
Completed Server Dialog

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).

Validate Server
Validate Server

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:

Deployment Dialog
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:

Mappings Tab
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:

Validate Server
Validate Server

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’.

Configuration Button
Configuration Button

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.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s