Skip to content

Instantly share code, notes, and snippets.

@vicgonvt
Last active April 5, 2019 18:29
Show Gist options
  • Save vicgonvt/aba1e7008c83af6ab20916e427d4a52f to your computer and use it in GitHub Desktop.
Save vicgonvt/aba1e7008c83af6ab20916e427d4a52f to your computer and use it in GitHub Desktop.
Instructions for Installing Xdebug in a Mac with Laravel, Valet and Sublime Text

NOTE: This assumes that you have Valet, Homebrew, Sublime Text and PHP properly installed and functioning and will only focus on the setup and installation and setup of Xdebug. There are other tutorials that go into great depth explaining how to get those tools installed on your mac.

Let's get started right away!

Installing Xdebug

You need to know which version of PHP you are running in your machine. To do so, from the terminal run the command php -v and this will display something like this

PHP 7.0.14 (cli) (built: Dec  8 2016 23:34:17) ( NTS )
Copyright (c) 1997-2016 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies
  • For PHP 5.5:
brew install php55-xdebug
  • For PHP 5.6:
brew install php56-xdebug
  • For PHP 7.0:
brew install php70-xdebug
  • For PHP 7.1:
brew install php71-xdebug

After Homebrew has completed the installation of Xdebug, you need to restart apache. Run the following command in the terminal:

sudo apachectl -k restart

Optional Tool for Mac OS X

There is a nice tool that allows you to quickly enable and disable Xdebug in Mac OS. While it is not required you may find it handy.

To Install run the following command in the terminal

brew install xdebug-osx

Usage

COMMAND               FUNCTION
xdebug-toggle         - outputs the current status
xdebug-toggle on      - enables xdebug
xdebug-toggle off     - disables xdebug

Sublime Text - Xdebug Client

Next, you will have to install a package for Sublime Text to handle the incoming Xdebug data. This step does require that you have Package Control installed which if you are using Sublime Text is a MUST! Go to https://packagecontrol.io/installation for instructions on how to get that setup if you don't already have it.

Open the command palette from the menu Tools > Command Palette... or with the keyboard shortcut Command+Shift+P and look for Package Control: Install Package. This will load all of the available packages, once it loads, look for Xdebug Client and hit Enter get it installed.

Once installed, a new menu item will appear at the bottom of the Tools menu. Browse there and click on Tools > Xdebug > Settings - User and copy in the following:

{
    "port": 9001
}

This setting avoids a conflict with Valet and allows it all to work together.

Edit PHP

It's time to make a small change to your php.ini file to allow Xdebug to transmit in the right frequency, if you will.

On your terminal run the following command

open /usr/local/etc/php/

This will open a new window in the Finder showing you one or more versions of PHP as directories. Open the appropriate version for your setup (HINT: Same as the one you used to install Xdebug in step 1) and look for a file called php.ini and drag it into Sublime to edit it's content. Go to the end of the file and paste in the following lines

[xdebug]
xdebug.remote_enable=on
xdebug.idekey="sublime.xdebug"
xdebug.remote_port=9001

These lines will turn on the remote debugging as well as set Sublime Text as the "listener" for all of the data Xdebug is going to send out. This is also where we set the port to match the settings we already put into Sublime Text.

Final Step

We have changed a lot of things with our settings and Valet and now we need to reboot it so it aquires it all successfully.

Go to your terminal and run the following command

valet restart

Confirmation & Artisan Usage

This completes the setup of Xdebug. The following are some troubleshooting and usage examples to get you started.

Check PHP

Open the terminal and run the following command

php -v

You've ran this command before but now, if you installed correctly, there will be an extra line at the bottom telling you what version of Xdebug you are running. Check it out! It should look something like this

PHP 7.0.14 (cli) (built: Dec  8 2016 23:34:17) ( NTS )
Copyright (c) 1997-2016 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies
    with Xdebug v2.5.0, Copyright (c) 2002-2016, by Derick Rethans

Debugging an Artisan Command

Open up an existing Laravel project or create a new one to begin playing around with Xdebug. In my case, I will start a fresh project by running laravel new xdebug in my terminal.

I will browse into the project folder and open it in Sublime Text.

Back in the terminal, I will run the following command to whip up a new command that I can play around with

php artisan make:command XdebugCommand

Browse to app/Console/Commands/XdebugCommand.php and replace it's content with the following code

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;

class XdebugCommand extends Command
{

    protected $signature = 'xdebug:test';

    protected $description = 'Testing Xdebug';

    public function handle()
    {
        $this->doSomething('Testing!');
    }

    public function doSomething($string)
    {
        dd($string);
    }
}

This is a super simple class just to get your feet wet with debugging with Xdebug.

Finally, let's add it to your Kernel.php file. Browse to app/Console/Kernel.php and find the empty array called $command and substitute the following code in.

protected $commands = [
    Commands\XdebugCommand::class,
];

Start debugging

You need to tell Sublime Text to start a new debugging session by going to Tools > Xdebug > Start Debugging This starts off a session for you. Next, you need to add a stopping point for Xdebug. What this does is run all of your code up to your stopping point and just halt there. This will then give you options to step into your code as much as you want. You can add as many of these as you'd like depending on what you need to debug.

Let's set a new breakpoint now.

Put your cursor in the line that reads $this->doSomething('Testing!'); and go to Tools > Xdebug > Add/Remove Breakpoint this will add a stopping point in this line of code so we can start debugging.

Now it's finally time to put it all together

On the terminal, run the following command

php -dxdebug.remote_autostart artisan xdebug:test

You will notice that it just halts and waits for you and if you switch back to Sublime Text, all of the panes are full of awesome bug-squashing information that give you tons of insight on your application. Now, let's start stepping forward into the code. You can use the menus but honestly you need to learn the keyboard shortcuts for this because you will be doing a lot of it. There is a lot to learn here but let's just do the basic one. Press Shift+Command+F7 and watch as the code executes line by line. Sublime Text will show a green arrow in the gutter to indicate which line it is executing, if you don't see it, you may have a conflicting package like GitGutter or similar. Remove that package or disable it when debugging.

Good Bye

Hope this will help everyone step away from the "var dumping" syndrome!

Happy Coding

Copy link

ghost commented Nov 22, 2017

Awesome, thanks!

@adc91
Copy link

adc91 commented Feb 14, 2018

Amazing!!

@michaelklopf
Copy link

This shouldn't work anymore, some major changes were made and it's driving me up the wall.

@dniccum
Copy link

dniccum commented Apr 12, 2018

Homebrew has completely re-worked all of their PHP taps and nothing is resolving.

@rebz
Copy link

rebz commented Apr 17, 2018

None of these work due to Homebrew changes.

@hayzem
Copy link

hayzem commented Apr 24, 2018

none of those formulas is working.

@stillfinder
Copy link

Doesn't work...

@rathorevaibhav
Copy link

did someone find anything regarding this?

@Pushplaybang
Copy link

doesn't work with new homebrew

@RDelorier
Copy link

As of homebrew 1.5.0 you will need to use pecl to install the xdebug extention.
pecl install xdebug-2.6.0
https://brew.sh/2018/01/19/homebrew-1.5.0/
Homebrew/homebrew-core#26362

@sajidunnar
Copy link

@RDelorier Thanks :)

@lubobill1990
Copy link

@RDelorier Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment