Using PhpStorm with Vagrant / Homestead

Here’s how to set up Php­Storm with Vagrant / Home­stead for local dev with Xde­bug for Craft CMS or oth­er PHP dev

Andrew Welch / nystudio107

There are many guides out there for using Php­Storm with Vagrant/​Homestead but many of them are out of date, and giv­en the stum­bling blocks I ran into, I fig­ured I’d put up a quick ​“how to” on the subject.

This is a very spe­cif­ic tuto­r­i­al. If you’re not using Php­Storm with Vagrant/​Homestead in order to do PHP devel­op­ment (or a mix of PHP and fron­tend devel­op­ment), it’s prob­a­bly of no inter­est to you at all.

So why would we use Php­Storm? In the words of an angry guy I know named Brad, ​“Frankly, I don’t know how any­one does PHP devel­op­ment with­out it.”

If you do any lev­el of PHP devel­op­ment, it’s worth the expense and set­up time to be able to set break­points, inspect vari­able val­ues, look at stack traces, and so on and so forth. The nor­mal things you’d expect from an Inte­grat­ed Devel­op­ment Envi­ron­ment (IDE).

The Be Awe­some in Php­Storm Lara­Casts are a must-watch (and free!) for any­one using PhpStorm.

My Secret Shame

Despite the fact that I’ve done a ton of PHP plu­g­in devel­op­ment, my secret shame is that I’ve been doing it all along with Sub­lime Text. That’s not a slight against Sub­lime Text, it’s a fan­tas­tic edi­tor. But it’s not an IDE, and attempt­ing to do devel­op­ment on any rea­son­able scale with­out an IDE is painful at best.

I made sev­er­al abort­ed attempts to get up and run­ning with Php­Storm, but I always ran into stum­bling blocks or flat-out did­n’t have the time to invest in get­ting it up and run­ning, and learn­ing how to use it effectively.

So my ​“one new thing” for an upcom­ing project is to get going with Php­Storm, come hell or high-water. If you’re doing any lev­el of PHP devel­op­ment pro­fes­sion­al­ly, don’t be like me. Get on board the Php­Storm express ASAP.

Get­ting Php­Storm up and Running

So let’s get things up and run­ning, shall we? This tuto­r­i­al assumes that you already have Vagrant installed and run­ning, and are using it for local dev. If you don’t have it up and run­ning yet, the video Set­up Craft CMS on Vagrant Home­stead will help you out.

First pro tip is when you fire up Php­Storm, don’t use any of its set­up wiz­ards. I’m sure there’s some way to get them to pro­duce the desired end-result, but I sure haven’t found it.

Instead, just go right to Open and choose your exist­ing root Craft CMS project install, and away you go.

The next thing we need to do is to tell Php­Storm that we’re using Vagrant. Go to PhpStorm→Preferences and then click on Tools→Vagrant. If you see an error mes­sage Error: Can't run Vagrant executable, even though Vagrant is prop­er­ly installed and work­ing, it’s pos­si­ble that the vagrant com­mand isn’t in your $PATH.

For instance, I had to enter the com­plete path to my vagrant exe­cutable: /usr/local/bin/vagrant Click on Apply.

Next we need to tell Php­Storm what PHP lan­guage lev­el (ver­sion) we’re using (PHP 7 is what I’d sug­gest every­one be using as a base now), and we need to choose the CLI Inter­preter that the project should be using inside of the Vagrant box.

Click on the lit­tle … next to to CLI Inter­preter so set the path to your Vagrantfile (usu­al­ly inside of your Homestead/ fold­er) so that Php­Storm knows where to find your Vagrant VM, and con­fig­ure your Remote PHP set­tings as appro­pri­ate, then click on Apply.

If it does­n’t show up, click the cir­cu­lar arrow icon for it to con­nect to your Vagrant box and inter­ro­gate it. Click on Apply.

Next we need to set up a Run Con­fig­u­ra­tion for our project. Go to Run→Edit Con­fig­u­ra­tions…

Then click on the + icon and choose PHP Web Appli­ca­tion , and give your Run Con­fig­u­ra­tion a name (I just name it after the project name). Choose the default web brows­er you’d like to use (I pre­fer Chrome, but what­ev­er works for you).

Next, we need to set up a serv­er for it to use for this Run Con­fig­u­ra­tion. Click on the lit­tle … but­ton next to the Serv­er drop­down menu, give your serv­er a name, enter the local URL, and make sure the Debug­ger is set to Xde­bug.

Check the Use path map­pings (select if the serv­er is remote or sym­links are used) check­box. Now we need to tell Php­Storm where our local files are on the serv­er. For instance, my project root on my local machine is /Users/andrew/webdev/sites/craft3 but it needs to be mapped to the absolute path /home/vagrant/sites/craft3 on the remote serv­er (our Vagrant box).

We need to add a map­ping for the root project, as well as any­thing else that is sym­linked. For instance, for plu­g­in devel­op­ment, the seomatic plu­g­in is a sym­link to it’s actu­al loca­tion else­where in my dev machine, so we need to add a map­ping for that, too.

While this may seem a lit­tle strange, remem­ber that Php­Storm is read­ing files from your local machine, but let­ting you run and debug them in a ​“remote” serv­er on our Vagrant box. So we need some way to tell it how to map these things.

Click on OK , then choose this new­ly cre­at­ed serv­er con­fig from the Serv­er: drop­down menu in the Run/​Debug Con­fig­u­ra­tions set­tings, then click on OK.

Are we there yet?

N.B.: This fol­low­ing been fixed in lat­er ver­sions of Home­stead, so the below may not apply to you… but it does­n’t hurt to san­i­ty check your Xde­bug settings.

No, we’re not there yet — but we’re very close! For what­ev­er rea­son, despite the fact that Home­stead includes Xde­bug, with it enabled by default, it isn’t ready to go for remote debug­ging. Which does­n’t make a whole lot of sense to me in the con­text of a Vagrant box. But anyway…

So we need to set it up. Do so by vagrant ssh​’ing to your Vagrant box, and then assum­ing you’re run­ning php7.0 edit the /etc/php/7.0/mods-available/xdebug.ini (you’ll need to sudo) file to look like this:

zend_extension=xdebug.so
xdebug.remote_autostart = 1
xdebug.remote_enable = 1
xdebug.remote_connect_back = 1
xdebug.remote_port = 9000
xdebug.max_nesting_level = 512

This tells it that we want to be able to use Xde­bug for remote debug­ging. Save it, then restart the php7.0-fpm ser­vice via sudo service php7.0-fpm restart and away you go.

If you’re run­ning PHP 7.1 with lat­er ver­sions of Home­stead, just sub­sti­tute 7.1 for 7.0 in the above paths/​comments.

You can now start enjoy­ing all of the Php­Storm IDE good­ness by Using the Run→Run Pro­ject­Name or Run→Debug Pro­ject­Name menu items.

Set break­points. Dive through stack traces. Do some­thing awesome.

Further Reading

If you want to be notified about new articles, follow nystudio107 on Twitter.

Copyright ©2020 nystudio107. Designed by nystudio107