How to config Homestead to debug our Laravel projects with Xdebug

If we are looking for debug our Laravel's code when using Homestead this is your post. There are out there a few goods guides to achieve this I'm basically putting toghether the best bits of each on this post.

The simple bit

Having in mind that ...

At the time to write this Homestead is doing most of the job for us, setting up everything needed, as you can see on the laravel/settler project which generates the vagrant box that we ended using with Homestead:

# Install PHP Stuffs

apt-get install -y php5-cli php5-dev php-pear \  
php5-mysqlnd php5-pgsql php5-sqlite \  
php5-apcu php5-json php5-curl php5-gd \  
php5-gmp php5-imap php5-mcrypt php5-xdebug \  
echo "xdebug.remote_enable = 1" >> /etc/php5/fpm/conf.d/20-xdebug.ini  
echo "xdebug.remote_connect_back = 1" >> /etc/php5/fpm/conf.d/20-xdebug.ini  
echo "xdebug.remote_port = 9000" >> /etc/php5/fpm/conf.d/20-xdebug.ini  
echo "xdebug.max_nesting_level = 250" >> /etc/php5/fpm/conf.d/20-xdebug.ini  

xdebug is being installed and configured out of the box, you can check it by run:

$ php -m | grep xdebug

And check if you want that have been installed

$ aptitude show php5-xdebug | grep Version

So what's the issue? ...

Basically this line in here was driving me crazy:

# Disable xdebug to prevent conflict
php5dismod xdebug  

It's seems like if you are using Blackfire homestead will disable xdebug to prevent conflicts, and no one is gonna told you about that...

To fix this we need to:

  • Disable Blackfire enable xdebug and restart php5-fpm as below:
$ sudo php5dismod blackfire
$ sudo php5enmod xdebug
$ sudo service php5-fpm restart

And we will be ready to go :)

The deeper part

Having in mind that we could destroy and up our machine at any point we are going to explain how to do this changes permanent so we wouldn't need to do the whole process again each time we re/create our machine.

Improve xdebug config


Trigger xdebug from command line (phpunit)

Add to your ~/.profile file the following:

export PHP_IDE_CONFIG="serverName=vagrant"  
export XDEBUG_CONFIG="idekey=PHPSTORM remote_host= profiler_enable=1"  


We'll just need to add the following to our script and re/create our machine.


The configuration below will just work fine for you however feel free to adapt it to cover your needs, for more details about hwo to config your xdebug visit their web site


This is how PHPStorm should looks like

If we want to debug of phpunit test or any other script through the command line:

Xdebug stand alone

What make xdebug works is this files:


To activate xdebug it have to be on fpm/conf.d

cd /etc/php5/fpm/conf.d  
sudo ln -s ../../mods-available/xdebug.ini 20-xdebug.ini  

After doing any of this changes we need of course restart php5-fpm

sudo service php5-fpm restart