Using PhpStorm with Vagrant / Homestead
Tags: phpstorm, homestead, vagrant, devops
Published: 2020-02-15 23:21:26

---
title: Using PhpStorm with Vagrant / Homestead
published: true
date: 2017-01-10 22:13:00 UTC
tags: phpstorm,homestead,vagrant,devops
canonical_url: https://nystudio107.com/blog/using-phpstorm-with-vagrant-homestead
---

# 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](https://nystudio107.com)

![Storm At Sea](https://nystudio107-ems2qegf7x6qiqq.netdna-ssl.com/img/blog/_1200x675_crop_center-center_82_line/storm-at-sea.jpg)

There are many guides out there for using [Php­Storm](https://www.jetbrains.com/phpstorm/) with [Vagrant/​Homestead](https://laravel.com/docs/5.3/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](https://laracasts.com/series/how-to-be-awesome-in-phpstorm) 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](https://github.com/nystudio107), my secret shame is that I’ve been doing it all along with [Sub­lime Text](https://www.sublimetext.com/). 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.

![Hidden Shame Face](https://nystudio107-ems2qegf7x6qiqq.netdna-ssl.com/img/blog/_1200x675_crop_center-center_82_line/hidden-shame-face.jpg)

So my [​“one new thing”](https://dev.to/gaijinity/frontend-dev-best-practices-for-2017-2ol9-temp-slug-5463385) 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](https://www.youtube.com/watch?v=DfUqciZ91oU) 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.

![Phpstorm Open](https://nystudio107-ems2qegf7x6qiqq.netdna-ssl.com/img/blog/_768x494_crop_center-center_100_line/phpstorm-open.png)

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 <kbd>Error: Can't run Vagrant executable</kbd>, even though Vagrant is prop­er­ly installed and work­ing, it’s pos­si­ble that the <kbd>vagrant</kbd> com­mand isn’t in your <kbd>$PATH</kbd>.

![Phpstorm Vagrant](https://nystudio107-ems2qegf7x6qiqq.netdna-ssl.com/img/blog/_992x689_crop_center-center_100_line/phpstorm-vagrant.png)

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

![Phpstorm Php Settings](https://nystudio107-ems2qegf7x6qiqq.netdna-ssl.com/img/blog/_992x689_crop_center-center_100_line/phpstorm-php-settings.png)

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 <kbd>…</kbd> next to to CLI Inter­preter so set the path to your <kbd>Vagrantfile</kbd> (usu­al­ly inside of your <kbd>Homestead/</kbd> 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…**

![Phpstorm Run Config](https://nystudio107-ems2qegf7x6qiqq.netdna-ssl.com/img/blog/_992x654_crop_center-center_100_line/phpstorm-run-config.png)

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

![Phpstorm Server](https://nystudio107-ems2qegf7x6qiqq.netdna-ssl.com/img/blog/_768x648_crop_center-center_100_line/phpstorm-server.png)

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 <kbd>/Users/andrew/webdev/sites/craft3</kbd> but it needs to be mapped to the absolute path <kbd>/home/vagrant/sites/craft3</kbd> 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 <kbd>seomatic</kbd> 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 <kbd>vagrant ssh</kbd>​’ing to your Vagrant box, and then assum­ing you’re run­ning php7.0 edit the <kbd>/etc/php/7.0/mods-available/xdebug.ini</kbd> (you’ll need to <kbd>sudo</kbd>) 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](https://xdebug.org/) for remote debug­ging. Save it, then restart the <kbd>php7.0-fpm</kbd> ser­vice via <kbd>sudo service php7.0-fpm restart</kbd> and away you go.

If you’re run­ning PHP 7.1 with lat­er ver­sions of Home­stead, just sub­sti­tute <kbd>7.1</kbd> for <kbd>7.0</kbd> 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](https://twitter.com/nystudio107) on Twitter._

<small>Copyright ©2020 nystudio107. Designed by nystudio107</small>