 Well, thanks for coming all. So today, we're going to be talking about debugging Drupal with xDbug. So if your interest is in front-end or CSS, this may not be the right session for you. But if you are interested in CSS and you want to expand your knowledge to PHP, then please stay. But most literally, this is for people who are already familiar with PHP and want to just expand their repertoire of tools. So without further ado, let's get started. So I'm Nick Dickinson-Wild. I work with Toyota Creative in Washington, DC. I've been working with Drupal for an amazing 10 years. I did not realize it had been 10 years until I was updating my information slide when I suddenly went, wait a second, it's been a couple of years without events. And suddenly, that seven is now just about 10. So yeah, I've been working with Drupal for 10 years. I have code samples for most of what I'm talking about on GitHub. I have a link there. And I will tweet that link later if anyone doesn't get it. And it's also at the end of our presentation. So our goal for today is understanding what xDbug is and where it excels and when it's not really worthwhile using it. We also want to install xDbug in a UNIX environment. I don't care whether you're using Docker or a nice Ubuntu local host or WSL on Windows or even a Mac. Any of these things can easily work with xDbug. So xDbug is one of my personal favorite tools. However, there is a certain facet of people who say that xDbug is the only debugging solution. And anyone who doesn't use xDbug is less experienced or less qualified. This is absolutely not the case. xDbug is a very good tool. It is not the be all and end all of debugging. So in terms of other options for debugging, we have DevL, which is a great contrib module. It improves a lot from standard PHP debugging. I rarely use either DevL or standard PHP debugging. They have totally good uses. I just don't generally use them because I'm used to xDbug. It's my favorite tool, so I go for it first. But if those two are your favorite tools, by all means, continue using them if you're not doing something that really is better with xDbug. So what is better with xDbug? Mostly it's if you're dealing with loops, whether you're doing a migration or a form API, or maybe you're dealing with an external API getting data. You're going through a lot of the same code paths, but you know there's a mistake somewhere, and until you get the right data, you won't hit that. So in that case, you can tell xDbug to only stop in certain cases so you get the right information to use. So xDbug is a PHP extension. It's written in C. It's been around for a long time, but almost as long as PHP itself, as well as step debugging, which is all I'm going to really talk about today. It also provides tracing, profiling, and code coverage analysis. They're all great tools. In my opinion, the step debugger is the best use of xDbug. The others are good, but they're harder to run and more work. So to get started with xDbug, you'll need either DDEV or Lando or any Unix system, really. On Windows, you theoretically can run xDbug, but it's a pain. So if you're on Windows, I highly recommend using either Windows subsystem Linux or Docker. And even if you're using Docker, running Docker through Windows subsystem Linux is much faster than through the Windows Hyper-V. So running xDbug doesn't just make you debug. You actually have to use a debugger. You do have a command line debugger that's included with xDbug. But it's very limited functionality. In almost all cases, you're better off with a debugger in your integrated development environment, whether that's PHP Storm or VS Code. Almost all modern IDS have a plugin to make it work. PHP Storm works out of the box and is my personal preference. So installing xDbug, there's pretty good documentation on it, on the website. But a lot of people still have challenges. So if you do have a challenge, using DDEV or Lando is a totally valid way to do it. They both come with Lando pre-installed and, in many cases, pre-configured. Not all cases you can do out of the box with Lando or DDEV, but it really does help if you have difficulties with the install portion. So if you're going to install it on your local environment, you can just use your package manager and do sudo apt or yum. Almost all package managers do have some name for xDbug, although the name differs in a bit of cases. Once you have xDbug installed, if you run PHP-B, you should see result something like this, where it shows what version of xDbug. You may see here that I'm using xDbug 3. There is differences with xDbug 2, especially in configuration. So if you're using xDbug 2, do take note and read the documentation on configuration, because otherwise your remote ports and debug options may fail. So most manual installs will need more configuration. But as I mentioned, I do have example configurations on GitHub, and I will go through them briefly today. So the most basic configuration you can just use in a PHP.ini custom one or in a specific xDbug configuration file, depending on how you have your PHP set up. You just set xDbug discovered client host to true. In most local host situations, this works. If you're using Docker or WSL, it may not, in which case you might need to actually set the client host to a real value. You'll need to have the debug mode into debug that's fairly straightforward. And if you're on Docker or WSL, you will need remote enable to true. In most cases, that will work outside the box, and you're good to go. If you are wanting to use command line debugging, you need to set a couple environment variables, which I've included here, PHP, IDE, config, server name equals local host. That local host can be any value you want. However, if you set to something else, you will need to tell what it is. You have to tell it if it's local host too, but in this example, I'm using local host throughout. And the xDbug session value can be really anything I just said to PHPStorm because I use PHPStorm, so it's nice, easy to remember thing. So one of the major problems with xDbug is performance. If you leave xDbug on when you're not using it, you will have a serious performance hit, easily 50% increase of load times, depending on your system, of course. The slower your system is, the worse the performance it will be. So I provide tooling on my Lando setups to disable and enable it just with the one command line. The same tooling can be used on basically any system you just would use these commands as a standalone command instead of wrapped in Lando. This is using the Lando configured with Nginx, so if you're using an Apache host or another host, then you would need to change the command to restart your hosting software, but it's pretty generic command. Again, with Lando, Lando works out of the box for website loads, but it doesn't work for command line, so if you're doing it with Lando, you need to tell it what environment variables. These are the same environment variables that I would use for command line in a non-Lando situation just defined in the Lando way instead of in Bash RC. So if you're using Windows subsystem Linux, there's a slight challenge in that every time you launch Windows, the client host changes. It's not a major challenge. It's defined in the resolve.conf within the Windows subsystem Linux every single load, but to have to manually update your configuration is a slight pain. So personally, I used this little grep and set to replace the configuration on my first launch. It's not the prettiest, but it works and is easier than manual. So we've gone over a basic install of XDbug before we move on to actually using XDbug. Is there any questions? Okay, so using XDbug, your ID will need to be configured minorly. Most IDs will just automatically pick it up, but you will need to tell it what the server information is, especially if you're using a remote host. So generally what I do when setting up a new system is I set PHPStorm to automatically break on the first line and listen to debug commands, and then it basically will tell you what information it's missing. So in this case, it doesn't know what this server and it provides a helpful link that you can click to get to the server configuration page. So here you'd enter localhost, which as I mentioned earlier, has to match your configuration of the environment variable. And then the path mapping depends on whether you're using a local host. If you're entirely local, you probably won't need to do path mapping. This example here is with Lando on Windows subsystem Linux. So the Lando path is slash app, whereas the subsystem Linux is a long path. A lot of IDs will complain if you have no breakpoint set that it ran, but there wasn't any connection. So is it misconfigured or what? This is a helpful warning, but in most cases I just ignore all because I know what I'm doing. I know it's going to work and it's just, it's annoying to see it stacking up if I don't run the right path. If you disable XD bug every single time, when you're not actively debugging, you won't see it anyways, but it's a lot easier if you do disable it. So for those of you who are not familiar with step debugging, step debugging, you just looking at your code, you decide of what line you want the code to pause execution. A good example of a step debugger is in the internet tools on any modern browser where you can step debug JavaScript. For PHP, it's basically the same concept and it works. So on this example here, we have both a red dot, that's one breakpoint, and then a second red dot where I've defined a case. If the destination property is anything else, it just walks right through this, which is one of the most important ways that you can use XD bug to save time. So the destination properties, you could have a hundred of them and you don't want to break on every single time. You only want to break on what you're interested in. So say your destination name, you know you need to do some pre-processing on it, but you don't know what the data is actually looking like because it's coming from an API. So every time you walk through this, you just say next and see what that data is looking like and get the right data. You can set this condition to any variable that is currently available. So if we're running a migration, I have a simple migration example here. The migration example is really unimportant for what I'm talking about, but this is the example I'm using just so you have a concept. So here we have a sample data. I've just made an example here with the number four here that has a very different date format. You know it failed at some point on migrating this large CSV file with 5,000 lines. You don't know when. So you just run it through XDBug and you say to stop on the published date field and then you get to see each value of that or you can also tell XDBug to only stop on errors. So in this case, we have a hit of a break point and any ID will then provide a list of both what the code path to get here was and what variables are available. In most cases, you can see what variables were available in the last step of the example. In most cases, this is all you need to do and to see what's wrong, but you can also individually just, you've got to this point, now you can step through one line at a time. Your break points provide the ability to pause your code, but at that point, you're now in full control once it's stopped. You can go line by line, you can step over a function or you can step into each individual function. With Drupal, you can step in deep. So sometimes it's a lot easier to just step over a line, especially if you're dealing with the form API or render API, the render API, you can go in so deep. Like you can literally go 30 iterations deep, which most cases is not very helpful when you're interested in one thing. So you may notice in this screen, we have a couple blue lines in the variables. This is a configurable what color it is depending on your eye, but XDbug says what lines of variables have changed since your last break point or your last step over, so that you know if you stepped over a function, you know what it actually did. So is there any questions about break points or where we are at so far? Yes, Karen. So in PHP Storm, you can right click the red dot and then you can suspend execution or get a conditional. The suspending execution just leaves the break point there so you can re-enable it at a later date. If you are happy with your data set for now, but you know it's going to change, so you want to keep that, you can bring up a list of suspended break points as well. And yes, so with all the break points, it stops at the start of the line. No, yeah. So some cases where your line is can be not as clear. Like if you put your break point at the middle of an array definition, it will go break at the start of the array definition because there's not actually a pause. That's one single execution. Yes, most I should have that functionality. I have used that in VS Code and PHP Storm. So if you, this is a recorded slide. So if you see on the right side of the above variables, there's some buttons there. One of those lists all the break points. Believe it's that blue three bars. And then you can suspend or disable break points or clear them all. Yeah, any other questions? So we've kind of talked about how we get to where we need to be with X debug, but haven't talked about how to best use it. Once you got to your point that you have a problem, you have this evaluate option. You have access to all the variables. You have all the information that PHP has. You can try everything here. You know what your publish date is. You know how it's being retrieved. You can now check out how does date time actually evaluate this. The beautiful thing is any errors here it doesn't stop your execution. So you can test out each command and find out what works with all your data types, update your code and then rerun it. And you can also set X debug to only break on errors. So once you're kind of happy with it, you think it's going to work. You can just run the whole set through until it gets an error. Then you do the same thing over. This evaluate box has all of the power of PHP. You can do anything you can in PHP. Doing imports of external files is a bit painful in there, but you can do it. So what I most often use it for is migrations that handle dates, but this is not a limit to how it can be used. Another thing you can do with most dives, definitely PHP Storm is well built for it, but I know VS Code can as well, is you can debug twig. To debug twig, you have to set twig to actually create the compiled files and tell your ID where to find them. If you set twig to debug mode, it often doesn't create the files, so you can't debug it, which is a bit confusing. So you set twig to compile, then you put your breakpoints into the non-compiled twig files, tell PHP Storm where they are, and then you can configure your debugger and just debug twig. The twig compiled files, they're a bit confusing if you don't know what you're looking at. They use a lot of obscure looking variables, but if you just put your breakpoints into the twig files, you get the right variables so you can evaluate what you're dealing with. Yeah, so, is there any more questions? For twig, unfortunately, I totally forgot to put it in the presentation. I generally do presentations with my laptop. I haven't done a totally pre-recorded presentation in two and a half years for some reason. I'm not sure really why, but I also seem to be sweating in my mask. I don't mind walking around, but actually talking for a bit, I notice it. So, to me, XDBug is crucial for working effectively, but it is not for everyone, and I really dislike the level of hierarchy that some people assign to whether you know XDBug or not means you're a good or bad developer. So, with XDBug, you can also, as I was talking, you can do command line debugging. That's great. You can actually debug Composer even on it, although I will say performance-wise, that is fun. Yeah, if we just go back to here, this is actually a migration that's running through a command line. So, you see the batch process? You can run it in batch processes within Ajax as well. Ajax is totally debuggable within XDBug. Yeah, well, we're half an hour, and somehow I keep doing this. My practice runs are always a bit slower. I feel that I talk faster when I'm in front of people. So, how you use XDBug is up to you. You can set tons of breakpoints or just one breakpoint and then walk through the code from there. Both are equally good. Some people like both ways. Feel free to experiment and practice with it to find your way. And again, definitely disable XDBug if you're not using it at the time or you will experience quite a significant slowdown. Here's that link again for the examples of configuration. I do have written documentation with each of the examples as well. So, before I let you all out early, did anyone else have any further questions? Yes. I can't say that I've found anything I can get in Kint that I can't get with XDBug. Kint does simplify the presentation of the data somewhat so that if you know what you're doing, you can possibly see that data quicker. Have you found any? Yeah. If you just need to print out your current variables and consider it without testing everything, XDBug is slow. So, run it through XDBug to get your basic what you need to deal with and then if you just need one data point, Kint is great. Yeah. I saw another hand raise. Rilanda. Well, to me it's a great tool in my toolbox but it's not a requirement. Yeah, it's a great tool. It saves me a lot of time personally. Will it save everyone time? Probably if they take the time to learn it and are working with back-end PHP and are working with loops enough. Humans just like hierarchies and hierarchies are generally bad because they're based on what you know instead of what you know in a specific situation. Hierarchies are meant to be flexible not based on, you know, this one skill. Yeah, I'm good with XDBug. There are people here that know Kint much better than me and could probably get the data just as quick as me with XDBug or possibly quicker if it's in this right situation versus this situation. Yeah. Yes. I'm not personally familiar with the XDBug configuration advisor or validation tool but if there is one it sounds very helpful for people. Yeah. Yeah. Once you have your debugger set up once it's like, okay, we just, new project, just enable it and you're good to go. Yeah, totally. Yes. Uh-huh. I don't know that you're a bad developer. Welcome to XDBug. So debugging Twig, you need to have the Twig compiled files actually be generated so that they aren't just in a temporary file that changes every single time you run it and then in your IDE you have to tell them where that is with PHPStorm you have your XDBug configuration where you can tell it to use a custom port if you need. In most cases, just leave the port the same but if you're in a special environment that port 9003 is used you might need to set the XDBug remote port to 9004 in which case your IDE has a setting to tell it what port to listen on and also in PHPStorm there's a Twig configuration page that's under XDBug that you can just set the path to your generated Twig files is sites default files PHP and then a bunch of random characters they're not really random but you can find your Twig folder in the files directory under PHP. Yes. Yeah, so that sounds to me like kind of the request loop probably I'm guessing that because that's the most complicated code that I generally accidentally wander into I know to avoid the render API unless I am actually doing something there so personally when I get somewhere like that and need to get out I use, I'll just go slide back I use the one more slide I use the left hand side the frames and go back to somewhere where I know and then I set a breakpoint just one line down from where it was executing before it went into the next layer and say skip to next breakpoint and I jump back to that point it's not quite popping the stack but yeah I guess. So, yeah that's the command line environment variables that I was showing the XD bug under bar session variable and the site name that was server name equals local host that generally does it depending on what your environment is you may need to make sure that XD bug is active for your command line PHP as well usually they're tied together if one's active the other is but in occasional situations you do have separate configuration so you need to activate XD bug for CLL as well as for live yeah you can only set breakpoints with XD bug in PHP you could set XD bugs in the PHP library that reads the YAML files in fact I have when I had mistakes in a migration definition that I couldn't figure out but you can't debug the YAML files directly anyone else? Well, it looks like 340 and thank you all for coming I should mention that Toyota is hiring US based developers and project managers if anyone wants to come work with me