diff --git a/public/img/blog/2024/05/xdebug_logo.png b/public/img/blog/2024/05/xdebug_logo.png new file mode 100644 index 0000000..917fd13 Binary files /dev/null and b/public/img/blog/2024/05/xdebug_logo.png differ diff --git a/src/content/blog/contributor-training.md b/src/content/blog/contributor-training.md index d547d59..2fa8da8 100644 --- a/src/content/blog/contributor-training.md +++ b/src/content/blog/contributor-training.md @@ -1,7 +1,7 @@ --- title: "DDEV Contributor Live Training" pubDate: 2023-07-09 -modifiedDate: 2024-04-24 +modifiedDate: 2024-05-27 summary: Live contributor training is available for those who want to learn to contribute and maintain DDEV. author: Randy Fay featureImage: @@ -11,7 +11,7 @@ categories: - Community --- -**TL;DR: Sign up for contributor training** on the form below to get the calendar invite with zoom link. +**TL;DR: Sign up for contributor training** at [DDEV Live Event meetup group](https://www.meetup.com/ddev-events/) to get invitations to trainings. As we announced in [Recruiting Contributors and Maintainers](/blog/recruiting-maintainers/) we're actively trying to increase the DDEV community of contributors and maintainers. To do that, we're going to start a series of trainings, and we'd love to have you come. The trainings will include information on how to contribute by: @@ -51,30 +51,25 @@ Live training sessions will be held weekly on Tuesdays at 8am US MT, 5pm CET or | 2023-11-07 | [DDEV Add-ons: Creating, maintaining, testing](https://www.dropbox.com/scl/fi/bnvlv7zswxwm8ix1s5u4t/2023-11-07_DDEV_Add-ons.mp4?rlkey=5cma8s11pscxq0skawsoqrscp&dl=0) see [outline](https://randyfay.notion.site/Contributor-Training-Add-ons-creating-maintaining-testing-1040f7d007c94bef8669a400a2437c98?pvs=4) | | 2023-11-14 | [DDEV Hosting Providers: Creating, Maintaining, Using](https://www.dropbox.com/scl/fi/yjgdjkiwwr4egyaewj40e/2023-11-14_DDEV_provider_integrations.mp4?rlkey=4ygpjaopgp2xbdswptsnzf50u&dl=0), see [outline](https://randyfay.notion.site/Contributor-Training-Provider-integrations-fb9676ca17d64fe6bf16a6b5b1622ccb?pvs=4). | | 2024-05-15 | [Debugging DDEV Go Code: Commands and Tests](https://www.youtube.com/watch?v=E-AEzC1p76E), see [blog](/blog/golang-debugging). | +| 2024-05-22 | [Xdebug and DDEV, How it works and Troubleshooting](https://www.youtube.com/watch?v=4MrwXTaHfnc), see [blog](/blog/xdebug-debugging). | **Upcoming Trainings:** +* DDEV Docker Architecture, including build stages +* Traefik Router Configuration and Possibilities +* Advanced DDEV Add-On Techniques +* DDEV automated tests and how to improve them +* Hostname Resolution and Debugging in DDEV +* Using AI in DDEV Development (Continue.dev, etc.) +* Interpreting `ddev debug test` To Support Users +* Maintaining DDEV Docker Images +* Implementing a New DDEV Project Type +* Managing and Maintaining DDEV Docs (Readthedocs.io, etc.) +* Using Tmate to Debug GitHub Workflows +* Using WSL2 with DDEV +* Git for Fun and Profit +* Making Your Own `ddev share` Variant +* Go Development Environment with Goland or vscode -| Training Date | Description | -|------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| -| [2024-05-22](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240522T08&p1=75&ah=1) | XDebug: Understanding, Using, and Sorting Out Problems | -| [2024-05-29](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240529T08&p1=75&ah=1) | DDEV Docker Architecture, including build stages | -| [2024-06-05](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240605T08&p1=75&ah=1) | Traefik Router Configuration and Possibilities | -| [2024-06-12](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240612T08&p1=75&ah=1) | Advanced DDEV Add-On Techniques | -| [2024-06-19](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240619T08&p1=75&ah=1) | DDEV automated tests and how to improve them | -| [2024-06-26](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240626T08&p1=75&ah=1) | Hostname Resolution and Debugging in DDEV | -| [2024-07-10](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240710T08&p1=75&ah=1) | Using AI in DDEV Development (Continue.dev, etc.) | -| [2024-07-17](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240717T08&p1=75&ah=1) | Interpreting `ddev debug test` To Support Users | -| [2024-07-24](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240724&p1=75&ah=1) | Maintaining DDEV Docker Images | -| [2024-07-31](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240731&p1=75&ah=1) | Implementing a New DDEV Project Type | -| [2024-08-07](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240807T08&p1=75&ah=1) | Managing and Maintaining DDEV Docs (Readthedocs.io, etc.) | -| [2024-08-14](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240814T08&p1=75&ah=1) | Using Tmate to Debug GitHub Workflows | -| [2024-08-21](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240821T08&p1=75&ah=1) | Using WSL2 with DDEV | -| [2024-08-28](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240828T08&p1=75&ah=1) | Git for Fun and Profit | -| [2024-09-11](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240911T08&p1=75&ah=1) | Making Your Own `ddev share` Variant | -| [2024-09-18](https://www.timeanddate.com/worldclock/fixedtime.html?msg=DDEV+Contributor+Training&iso=20240918T08&p1=75&ah=1) | Go Development Environment with Goland or vscode | - -Sign up on the simple form below to get the calendar invite with Zoom link. Drop by [Discord](https://discord.gg/5wjP76mBJD) or send [an email](mailto:support%40ddev.com) if you want to talk more. - - +Please join the [DDEV Live Event meetup](https://www.meetup.com/ddev-events/) to get notified about upcoming trainings. Drop by [Discord](https://discord.gg/5wjP76mBJD) or send [an email](mailto:support%40ddev.com) if you want to talk more. diff --git a/src/content/blog/xdebug-debugging.md b/src/content/blog/xdebug-debugging.md new file mode 100644 index 0000000..ef5e3e0 --- /dev/null +++ b/src/content/blog/xdebug-debugging.md @@ -0,0 +1,87 @@ +--- +title: "DDEV and Xdebug: Debugging and sorting out problems" +pubDate: 2024-05-28 +# modifiedDate: 2024-04-23 +summary: How Xdebug works with DDEV, and how to debug problems +author: Randy Fay +featureImage: + src: /img/blog/2024/05/xdebug_logo.png + alt: Xdebug logo + credit: 'Xdebug logo from https://en.m.wikipedia.org/wiki/File:Xdebug_Logo.svg' +categories: + - Guides +--- + +PHP developers have long had a variety of complications using Xdebug. It's a network protocol, which means that firewalls and other network complications can confuse things. And often people just don't understand how it works. We'll try to sort out how Xdebug works in general, and explain what that means in DDEV, and how to debug problems. + +Here's a recording of our [Xdebug contributor Training](https://www.meetup.com/ddev-events/events/301101460/) walking through DDEV and Xdebug. Please sign up on the [meetup](https://www.meetup.com/ddev-events/) so you'll get notified of future trainings. + + + +First of all, congratulations for making step-debugging a priority. It's my opinion that step-debugging is one of the very first things to learn in any language or environment that we undertake. + +Second, please [contribute to the Xdebug project](https://xdebug.org/support). Derick Rethans created this incredible resource and has been maintaining it for 22 years and counting. Making open-source projects sustainable is an obligation for all of us! + +DDEV's Xdebug [documentation](https://ddev.readthedocs.io/en/stable/users/debugging-profiling/step-debugging/) and [Xdebug troubleshooting section](https://ddev.readthedocs.io/en/stable/users/debugging-profiling/step-debugging/#troubleshooting-xdebug) will normally get everyone going, but we'll approach those from a slightly different perspective. + +## Basic Usage + +The [simplest DDEV Xdebug usage](https://ddev.readthedocs.io/en/stable/users/debugging-profiling/step-debugging/) is just: + +* `ddev xdebug on` +* Make your IDE listen for Xdebug +* Visit a page in your web browser + +In general, that's all you have to know. The exact details for PhpStorm and Visual Studio Code are provided in the docs, but this will work with any IDE that can do PHP step debugging, including NetBeans or even Eclipse. + +## How Xdebug works + +Xdebug is a network protocol. When `php` or `php-fpm` is executed and Xdebug is enabled in it, it will try to contact the IDE specified in the PHP setting `xdebug.client_host`. On DDEV this value is automatically set to `host.docker.internal`, and DDEV tries to make sure that `host.docker.internal` is set appropriately inside the `ddev-webserver` container on all platforms and Docker providers. + +If you have `ddev xdebug on` and you execute PHP code, normally by visiting a URL in your project, the `php` process will attempt to contact the IDE using `host.docker.internal` and port 9003. If there are appropriate path mappings in the IDE, and the IDE is listening, everything "just works" from there. + +## Demonstrating Xdebug's behavior + +You can easily test this out using the handy network utility `nc` or `netcat`. + +On your host workstation (the same place your IDE is running) you can +``` +nc -l 0.0.0.0 9003 +``` + +(note that different versions of `netcat/nc` may take slightly different arguments.) + +If you then visit your project, for example with `ddev exec curl localhost` or `curl https://.ddev.site` you'll see something like this pop up in the `nc` session: + +```xml +476 + +``` + +That's exactly what your IDE receives from PHP in the same situation. + +## Troubleshooting + +There is an extensive set of [troubleshooting instructions](https://ddev.readthedocs.io/en/stable/users/debugging-profiling/step-debugging/#troubleshooting-xdebug) in the DDEV docs, but remember that for most people there are most-common reasons for trouble: + +1. Your website is not executing the code where you have the breakpoint set, so it doesn't stop at your breakpoint. (Avoid this one by telling your IDE to stop at the first line no matter what, or by settings a breakpoint at the first line of your `index.php`.) +2. You do not have your IDE set up to map your code to the code in the container successfully. Your `index.php` path on the workstation host should map to the path inside the container (often something like `/var/www/html/web/index.php`) +3. You forgot to `ddev xdebug enable` or forgot to have your IDE listen for Xdebug. + +You may have problems beyond those in some environments, and they are often firewall-related. They can be sorted out by temporarily disabling your firewall and testing simple connectivity from the DDEV web container to the IDE. For example, make your IDE listen, then `ddev ssh` and `telnet host.docker.internal 9003`. If you get a connection there, and then *do not* get a connection when you tell your IDE to stop listening, you likely have all the networking problems sorted out. + +### WSL2 Complexities and Troubleshooting + +WSL2 is a complex networking environment, and it's made more complex by the fact that most developers run their IDE on the Windows side, while running DDEV in WSL2. That means that DDEV has to figure out how to set `host.docker.internal` to the right IP address for your Windows IDE. DDEV tries hard and usually succeeds! + +As a result of the complexity, there's an additional set of [WSL2 Xdebug debugging instructions](https://ddev.readthedocs.io/en/stable/users/debugging-profiling/step-debugging/#wsl2-xdebug-troubleshooting) in the docs. + +Remember that if you're one of the very unusual people who runs the Linux version your IDE inside WSL2, you'll be using `ddev config global --xdebug-ide-location=wsl2`. This is quite unusual. + +On any platform you can use `DDEV_DEBUG=true ddev start` and it will explain to you where `host.docker.internal` comes from with an explanation like this: `host.docker.internal='172.22.192.1' because IsWSL2 and !IsDockerDesktop; received from ip -4 route show default`. This can be especially helpful on WSL2. + +## Contributions welcome! + +We always love to hear your experiences with DDEV, so please do a PR to this blog adding your experience. Info and a training session on how to do a PR to anything in ddev.com is at [DDEV Website For Contributors](/blog/ddev-website-for-contributors/). And if you can improve the DDEV docs, click the pencil at the top of any docs page to add your suggestion. + +And join us most Wednesdays for [DDEV Live Contributor Training](https://www.meetup.com/ddev-events/). Past trainings are recorded at [contributor training](/blog/contributor-training). \ No newline at end of file