Setting Up XDebug

Using Xdebug makes it feel like anything else is coding while blind pressing keys with a long stick. It's absolutely needed to build out things in PHP when you don't know exactly how everything is working. So getting it working in our setup is very important. Currently this guide will only explain how to get Xdebug working in PHPStorm with our docker setup. Hopefully from there you can figure out how to get it to work in other editors or other projects and when you do, please add it.

Turning on Xdebug in your docker container

To get it turned on in your docker container you just need to modify your docker-compose yaml file. In our Drupal projects the lines you need are already there, you just need to comment them back in. Your compose.yaml should look like the one we have in GitHub. In the file you'll see the following lines:

...
#LOCAL: "true"
...
...
extra_hosts:
# - "xdebug:192.168.237.237"

Those both need to be commented back in. The local true means xdebug gets enabled and configured when the container is booted up. The extra hosts lets the container and your computer talk to eachother over that IP as that's what xdebug needs to work.

Once you have done that you're good to boot up your container, once it's booted you have step 1 of getting xdebug done.

Adding Loopback

Now we need to add the loopback, so your computer and your container can talk to eachother. If you ran Kerry's setupdev.sh you should already have this but I'll outline what to do again so you have it.

Mac

Get the docker-compose repo downloaded locally if you don't have it already.

Once you have that go to that directory in terminal and type ./addloopback.sh that will output some things into your terminal so you know it works.

That's it.

Linux

On Linux we currently don't have an awesome bash script, and this you have to run everytime your network changes, but hopefully I can make this awesome and stay forever like the Mac one but for now you can run

sudo ip addr add 192.168.237.237/24 brd + dev wlp4s0 label wlp4s0:1

You will have to change wlp4s0 to be your network devices name, and you can change the IP address to be anything, but it just needs to match the IP in your compose.yaml file.

Configuring PHPStorm

As of PHPStorm 2017.x getting PHPStorm working with xdebug & docker is a lot easier. If you are on an old version you should update first before continuing.

Configuring Docker

Here is jetbrains info on how to do this but it's actually long and has a lot of old things you might not want or need. As of September 2017 what is below does work but if you run into issues please refer to jetbrains docs and update these to reflect the changes.

1. Open the settings pane in PHPStorm (Control+Alt+S) or (Command+Alt+S) or File > Settings.
2. Search for Docker (or find docker under the "Build, Execution, Deployment" section)
3. Click the green plus to add a docker setup
   • If you get to this step and you already have a docker there continue to the 6th step
4. You can name this configuration "Docker" or whatever, and tell it to connect with the Unix Socker or Docker for Mac depending on your system
5. Click apply and ok.
6. You should now have a Docker icon somewhere in the bottom left of your screen, maybe hidden behind a menu icon. Click that.
7. That will have opened a pane just saying Docker, double click that docker icon.
8. If after clicking it it says connected and shows that docker containers are currently running you have succeeded. If not please scream and run around and ask for help.

Configuring this project

1. Now we need to configure Xdebug for this current project you have open in PHPStorm. To do this you will click a dropdown arrow on the top right of the window to the left of a green bug and play button.
2. Form there you click the "edit configurations" option
3. You will then click the green + on this pane and click the option "PHP Web Application" (for me I have to scroll to see that)
4. This should get you a screen that looks like this:
5. Click the ... next to the Server select list
6. This will bring up a new pan to configure the server (docker container)
7. From here you will name the server whatever (the name of the project)
8. Your host will be whatever url you go to to access the site (mycoolsite.dev)
9. Next you will want to use path mappings, so click that checkbox which will reveal new things on the pane.
10. Next you will configure your path mappings.
    • On the left side of the pane will show your local file system of this project. The right column is your server's file system.
    • You will just take whatever is on the right and prepend /var/www/site to it.
    • The general rule is to map docroot and every directory you will be working out of.
11. Click apply & ok.
12. Go ahead and name you confiuration the name of your project as well.
13. Click apply & ok.

Triggering it with PHPStorm

Now to actually use xdebug you will go any php file and to the left of the line and to the right of the number click and you will see a red circle appear, that's a breakpoint. A breakpoint is a spot that then the code is executing will stop at that point and show you everything that's happening. One trick is you can only place breakpoints in lines of actual code that will be executed, not just randomly at a spot in a file.

Once you have your breakpoints you want to see what is happening at, go ahead and click the green bug in the top right bar of the program. Clicking that will open a new page on PHPStorm and open your app in a browser window.

On that page it opens in the console, but that's probably not what you want, you'll want to go and click on the Debugger tab. If you're super lucky and your code executed already it's possible when you go to that tab you already see xdebug things!

If you didn't it's likely that your code doesn't run on the home page, that's fine just go to that page, but leave the ?XDEBUG_SESSION_START=XXXXXXX in the URL. If that still doesn't work then you most likely have to clear the cache.

If after that, it still doesn't work ask Josh.

:wq