wp-env: Xdebug support #27346

noahtallen · 2020-11-28T00:49:34Z

Description

Installs Xdebug 3 in the wp-env WordPress service.

How has this been tested?

It should work, but I can't test it since my IDE can't connect to it.

Setup environment

Run npx wp-env start --update --xdebug to rebuild the docker image with Xdebug (and to enable xdebug)

IDE setup

This will depend on your IDE. look for the PHP debug function (or extension) in your IDE, and make sure the key settings like "port" and "pathMappings" match the settings given for VS Code.

Install the "PHP Debug" extension for VS Code
Add this configuration to your VS Code launch.json

		{
			"name": "Listen for XDebug",
			"type": "php",
			"request": "launch",
			"port": 9003,
			"pathMappings": {
				"/var/www/html/wp-content/plugins/gutenberg": "${workspaceRoot}/"
			}
		}

Run the "listen for XDebug" action from the VS Code debug menu:

4. Set a breakpoint in a PHP file like `lib/load.php` and refresh your browser at `localhost:8888` 5. Breakpoint should trigger:

Public API:

Xdebug will be installed for all wp-env users by default, but set to the "off" mode, which adds zero overhead. To enable basic debugging with xdebug, simply run npx wp-env start --xdebug. Beyond that, you can set any Xdebug mode like so: npx wp-env start --xdebug=trace,gcstats.

Other considerations:

Should we include the launch.json file in the repository?

noahtallen · 2020-11-28T00:50:51Z

packages/env/lib/init-config.js

@@ -55,3 +64,18 @@ module.exports = async function initConfig( { spinner, debug } ) {

 	return config;
 };
+
+function dockerFileContents( image, xDebugMode ) {


I think it's helpful to have our own Dockerfile at this point. I imagine this could open up the path to some other features too.

github-actions · 2020-11-28T00:58:12Z

Size Change: 0 B

Total Size: 1.21 MB

ℹ️ View Unchanged

Filename	Size	Change
`build/a11y/index.js`	1.14 kB	0 B
`build/annotations/index.js`	3.8 kB	0 B
`build/api-fetch/index.js`	3.42 kB	0 B
`build/autop/index.js`	2.83 kB	0 B
`build/blob/index.js`	665 B	0 B
`build/block-directory/index.js`	8.72 kB	0 B
`build/block-directory/style-rtl.css`	943 B	0 B
`build/block-directory/style.css`	942 B	0 B
`build/block-editor/index.js`	128 kB	0 B
`build/block-editor/style-rtl.css`	11.2 kB	0 B
`build/block-editor/style.css`	11.2 kB	0 B
`build/block-library/editor-rtl.css`	9.07 kB	0 B
`build/block-library/editor.css`	9.07 kB	0 B
`build/block-library/index.js`	149 kB	0 B
`build/block-library/style-rtl.css`	8.35 kB	0 B
`build/block-library/style.css`	8.35 kB	0 B
`build/block-library/theme-rtl.css`	789 B	0 B
`build/block-library/theme.css`	790 B	0 B
`build/block-serialization-default-parser/index.js`	1.88 kB	0 B
`build/block-serialization-spec-parser/index.js`	3.06 kB	0 B
`build/blocks/index.js`	48.1 kB	0 B
`build/components/index.js`	172 kB	0 B
`build/components/style-rtl.css`	15.3 kB	0 B
`build/components/style.css`	15.3 kB	0 B
`build/compose/index.js`	10.2 kB	0 B
`build/core-data/index.js`	15.4 kB	0 B
`build/data-controls/index.js`	827 B	0 B
`build/data/index.js`	8.97 kB	0 B
`build/date/index.js`	31.8 kB	0 B
`build/deprecated/index.js`	769 B	0 B
`build/dom-ready/index.js`	571 B	0 B
`build/dom/index.js`	4.95 kB	0 B
`build/edit-navigation/index.js`	11.1 kB	0 B
`build/edit-navigation/style-rtl.css`	881 B	0 B
`build/edit-navigation/style.css`	885 B	0 B
`build/edit-post/index.js`	306 kB	0 B
`build/edit-post/style-rtl.css`	6.49 kB	0 B
`build/edit-post/style.css`	6.47 kB	0 B
`build/edit-site/index.js`	24.7 kB	0 B
`build/edit-site/style-rtl.css`	3.93 kB	0 B
`build/edit-site/style.css`	3.93 kB	0 B
`build/edit-widgets/index.js`	26.3 kB	0 B
`build/edit-widgets/style-rtl.css`	3.13 kB	0 B
`build/edit-widgets/style.css`	3.13 kB	0 B
`build/editor/editor-styles-rtl.css`	476 B	0 B
`build/editor/editor-styles.css`	478 B	0 B
`build/editor/index.js`	43.4 kB	0 B
`build/editor/style-rtl.css`	3.85 kB	0 B
`build/editor/style.css`	3.84 kB	0 B
`build/element/index.js`	4.62 kB	0 B
`build/escape-html/index.js`	735 B	0 B
`build/format-library/index.js`	6.74 kB	0 B
`build/format-library/style-rtl.css`	547 B	0 B
`build/format-library/style.css`	548 B	0 B
`build/hooks/index.js`	2.27 kB	0 B
`build/html-entities/index.js`	622 B	0 B
`build/i18n/index.js`	3.57 kB	0 B
`build/is-shallow-equal/index.js`	698 B	0 B
`build/keyboard-shortcuts/index.js`	2.54 kB	0 B
`build/keycodes/index.js`	1.94 kB	0 B
`build/list-reusable-blocks/index.js`	3.1 kB	0 B
`build/list-reusable-blocks/style-rtl.css`	476 B	0 B
`build/list-reusable-blocks/style.css`	476 B	0 B
`build/media-utils/index.js`	5.31 kB	0 B
`build/notices/index.js`	1.82 kB	0 B
`build/nux/index.js`	3.42 kB	0 B
`build/nux/style-rtl.css`	671 B	0 B
`build/nux/style.css`	668 B	0 B
`build/plugins/index.js`	2.56 kB	0 B
`build/primitives/index.js`	1.43 kB	0 B
`build/priority-queue/index.js`	789 B	0 B
`build/redux-routine/index.js`	2.84 kB	0 B
`build/reusable-blocks/index.js`	2.92 kB	0 B
`build/rich-text/index.js`	13.4 kB	0 B
`build/server-side-render/index.js`	2.76 kB	0 B
`build/shortcode/index.js`	1.69 kB	0 B
`build/token-list/index.js`	1.27 kB	0 B
`build/url/index.js`	2.84 kB	0 B
`build/viewport/index.js`	1.86 kB	0 B
`build/warning/index.js`	1.14 kB	0 B
`build/wordcount/index.js`	1.22 kB	0 B

_{compressed-size-action}

packages/env/lib/init-config.js

derickr · 2020-12-01T23:21:18Z

"The big problem is that Xdebug just got a brand new version (version 3), but all of the debugging extensions for VS Code (my IDE) are no longer maintained, so they don't support the new version. "

That's not true. IDEs continue to support Xdebug 3 just as they support Xdebug 2. The only change is that Xdebug's settings are different, and that the default port changed from 9000 to 9003 so that it does not conflict with PHP-FPM any more. Upgrade guide → https://xdebug.org/docs/upgrade_guide

noahtallen · 2020-12-02T02:06:32Z

Alright, I will try again then. I did update the local settings to match the new version but had no luck getting it to connect. It looks like folks have had some success here since I looked into it: xdebug/vscode-php-debug#411

noahtallen · 2020-12-02T23:43:42Z

@derickr Thanks for reminding me to look a little more closely! I was able to get it working. I think the problem was that discover_client_host doesn't work with docker in macOS from what I gather. Setting client_host to host.docker.internal (only on mac and windows) gets the VS Code debugger to connect.

derickr · 2020-12-03T00:04:25Z

Yes, discover_client_host doesn't play well with Docker. At least Xdebug 3 should be more chatty at what it is trying to connect to and why. The new xdebug_info() function is useful too for diagnostics.

jeyip · 2020-12-07T23:33:35Z

The debugging itself works wonderfully for me 🎉

Reviewing the code now

jeyip · 2020-12-07T23:43:23Z

Should we include the launch.json file in the repository?

The only reason I can think of not to include the file is to avoid cluttering the root for people who don't use xdebug, but adding it makes sense to me.

jeyip · 2020-12-08T00:57:11Z

Hmmm...had this working great earlier. Realized the HEAD of my local branch was outdated, and pulled the latest changes. Now xdebug won't recognize breakpoints anymore 🤔

I've tried cleaning the WordPress instance, destroying the docker volumes and starting over, and restarting my computer. No luck yet.

jeyip · 2020-12-08T01:30:06Z

I think I can reproduce the issue:

npx wp-env destroy && npx wp-env start --xdebug or npx wp-env start --update --xdebug
cat ~/.wp-env/[WORDPRESS_SHA]/Dockerfile
Note that, despite including the --xdebug flag, the initial Dockerfile contains RUN echo 'xdebug.mode=off' >> /usr/local/etc/php/php.ini
docker exec -it [WORDPRESS_CONTAINER_ID] /bin/bash
cd /usr/local/etc/php
cat php.ini
Note that xdebug.mode=off

Running a subsequent npx wp-env start --xdebug does update the Dockerfile, but it does not update the php.ini file in the docker container.

Debugging on my end shows that, for some odd reason, packages/env/lib/init-config.js:32 receives an undefined xdebug argument, even though the xdebug passed through packages/env/lib/commands/start.js:50 has the correct value of "debug" 😕

jeyip · 2020-12-08T01:32:05Z

This might be a local development issue -- let me know if you're able to reproduce the problem @noahtallen . If not, I'll keep trying to dig around and fix the issue on my mac.

noahtallen · 2020-12-08T03:12:17Z

I'll look into that, it definitely sounds like a bug.

BTW, some wp-env tips that might be useful for your use case!

docker exec -it [WORDPRESS_CONTAINER_ID] /bin/bash

You can replace that command with wp-env run wordpress bash. (Or replace wordpress with "cli" (for WP-CLI), or "tests-wordpress" for the tests instance)

cat /usr/local/etc/php/php.ini

You can also run this directly: npx wp-env run wordpress "bash -c 'php -ini'"

Might be more ergonomic to use than using the container ID ;)

jeyip · 2020-12-08T06:25:31Z

You can replace that command with wp-env run wordpress bash

You can also run this directly: npx wp-env run wordpress "bash -c 'php -ini'"

Thanks for those! I'll add them to my notes 😃

jeyip · 2020-12-09T00:34:16Z

I've resolved it by making only the start command writes changes to any of the docker configuration. I don't think this should affect any use cases. It makes total sense to me to putting a hard requirement on running wp-env start before using anything else -- this was already mostly the case.

This makes total sense to me as well. 👍 I'm not as familiar with all the use cases, but in my day-to-day workflow, I don't imagine this affecting my dev process either. I'm on board with this solution.

Side note -- do you think it would be overkill to add a note in the docs? I can't imagine these changes causing a problem in the future, but I've been wrong in the past 😛

noahtallen · 2020-12-09T00:35:04Z

yep :)

I think the only use case I can think of is running something like npm run lint-php, which probably didn't require wp-env start to be run in the first place.

jeyip · 2020-12-09T00:35:21Z

Testing the changes now. Will update this comment as I progress.

Tested outdated commit to confirm bug
Checked out latest commit and ran npx wp-env start --update --xdebug
Confirmed that the Dockerfile and php.ini in the docker instance have xdebug.mode=debug
It works! So cool 🎉
Error handling works as expected when I enter in an invalid xdebug value

jeyip · 2020-12-09T00:55:20Z

I noticed that php.ini is only updated when I run the start command with the update flag

For example:

I run npx wp-env start --update --xdebug
Then I run npx wp-env start --xdebug=trace The Dockerfile is updated, but php.ini isn't.
When I run npx wp-env start --update --xdebug=trace, php.ini updates

Is this expected?

+1 whenever we resolve this conversation 🙂

noahtallen · 2020-12-09T00:57:25Z

Hmm, that is unexpected, but I understand what is happening. I don't think Docker rebuilds the image unless the update flag is passed, which means the commands won't get set. I think I have a fix.

jeyip · 2020-12-09T00:59:25Z

Hmm, that is unexpected, but I understand what is happening. I don't think Docker rebuilds the image unless the update flag is passed, which means the commands won't get set. I think I have a fix.

Nice! Thanks for working on this Noah. Installing and setting up xdebug in this environment feels so easy ⭐️

noahtallen · 2020-12-09T01:03:15Z

Fixed in dad241a.

Installing and setting up xdebug in this environment feels so easy

Thanks!

jeyip · 2020-12-09T01:20:52Z

Ahhh so close. So the config files are all updating properly, but now the debugger no longer works. It's not recognizing my breakpoints.

I saw that you removed the launch.json file, so I recreated it and copied the settings from the PR description. Should I be doing anything else?

noahtallen · 2020-12-09T01:22:50Z

I saw that you removed the launch.json file, so I recreated it and copied the settings from the PR description. Should I be doing anything else?

Not that I know of, other than running wp-env start --xdebug. I'll test too

noahtallen · 2020-12-09T01:25:47Z

@jeyip it's working for me. Here's my launch.json in whole:

{
	// Use IntelliSense to learn about possible attributes.
	// Hover to view descriptions of existing attributes.
	// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
	"version": "0.2.0",
	"configurations": [
		{
			"name": "Listen for Xdebug",
			"type": "php",
			"request": "launch",
			"port": 9003,
			"pathMappings": {
				"/var/www/html/wp-content/plugins/gutenberg": "${workspaceRoot}/"
			}
		}
	]
}

the part in the PR description is just an individual entry

jeyip · 2020-12-09T01:29:59Z

Yeah that's what I had as well. Not sure why it wasn't catching, but I restarted my terminal / editor and it works now 🤷‍♂️

Aaaaannnnd let's !

ajgagnon · 2020-12-09T16:24:09Z

Woohoo! 🎉

Any change this can be updated on the npm package? I'd love to use xdebug on my own project.

https://www.npmjs.com/package/@wordpress/env

noahtallen · 2020-12-09T18:27:34Z

Unfortunately, wp-env has to be updated along with the rest of the npm packages in the monorepo, which hasn’t happened since before the latest WordPress release cycle. So I expect we can get a new version out in the next few weeks

ajgagnon · 2020-12-11T20:29:27Z

Ah, okay no problem. Thanks for the reply!

pbking · 2020-12-16T20:11:25Z

@ajgagnon you can install the module yourself until it's out:

remove the existing wp-env module npm uninstall -g @wordpress/env
from the Gutenberg project path /packages/env install what you have checked out (/master branch has this change) npm install -g

Now the instance of wp-env that you run will be what you installed from your local filesystem.

Just remember to uninstall that one and install the official again once another version ships. This was too valuable a feature to wait on though...

noahtallen requested a review from noisysocks November 28, 2020 00:49

noahtallen requested a review from epiqueras as a code owner November 28, 2020 00:49

noahtallen commented Nov 28, 2020

View reviewed changes

noahtallen added [Tool] Env /packages/env [Status] In Progress Tracking issues with work in progress [Type] Enhancement A suggestion for improvement. labels Nov 28, 2020

noahtallen self-assigned this Nov 28, 2020

derickr reviewed Dec 1, 2020

View reviewed changes

packages/env/lib/init-config.js Outdated Show resolved Hide resolved

noahtallen force-pushed the try/wp-env-xdebug branch from 9528563 to 4d441d4 Compare December 2, 2020 23:34

noahtallen requested review from spacedmonkey and TimothyBJacobs as code owners December 2, 2020 23:34

noahtallen mentioned this pull request Dec 2, 2020

Xdebug 3 compatibility xdebug/vscode-php-debug#411

Closed

noahtallen removed the [Status] In Progress Tracking issues with work in progress label Dec 3, 2020

noahtallen force-pushed the try/wp-env-xdebug branch 2 times, most recently from be5c2d0 to bdbdbfc Compare December 7, 2020 22:23

noahtallen added 3 commits December 8, 2020 15:21

Install xDebug in wp-env

2a80bf4

Fix client detect settings

616f740

Remove xdebug_info call

cf9ad7c

More verbose error message

3269bdd

noahtallen added 2 commits December 8, 2020 16:40

Update changelog

85cde08

Remove launch.json

4109fd6

Update changelog again

c4c3b3d

Make sure config is different when xdebug param changes

dad241a

Fix typo

d62cdb6

Add Xdebug documentation

6f9ad25

jeyip approved these changes Dec 9, 2020

View reviewed changes

Add launch.json config for Xdebug

8de5ae8

jeyip approved these changes Dec 9, 2020

View reviewed changes

noahtallen merged commit 454c708 into master Dec 9, 2020

noahtallen deleted the try/wp-env-xdebug branch December 9, 2020 04:11

github-actions bot added this to the Gutenberg 9.6 milestone Dec 9, 2020

swissspidy mentioned this pull request Dec 9, 2020

wp-env: Add Xdebug support #20636

Closed

swissspidy mentioned this pull request Dec 17, 2020

wp-env: docker-compose fails on PHP < 7.2 due to Xdebug #27783

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

wp-env: Xdebug support #27346

wp-env: Xdebug support #27346

noahtallen commented Nov 28, 2020 •

edited

Loading

noahtallen Nov 28, 2020

github-actions bot commented Nov 28, 2020 •

edited

Loading

derickr commented Dec 1, 2020

noahtallen commented Dec 2, 2020

noahtallen commented Dec 2, 2020

derickr commented Dec 3, 2020

jeyip commented Dec 7, 2020

jeyip commented Dec 7, 2020

jeyip commented Dec 8, 2020

jeyip commented Dec 8, 2020 •

edited

Loading

jeyip commented Dec 8, 2020

noahtallen commented Dec 8, 2020 •

edited

Loading

jeyip commented Dec 8, 2020

jeyip commented Dec 9, 2020 •

edited

Loading

noahtallen commented Dec 9, 2020

jeyip commented Dec 9, 2020 •

edited

Loading

jeyip commented Dec 9, 2020

noahtallen commented Dec 9, 2020

jeyip commented Dec 9, 2020

noahtallen commented Dec 9, 2020

jeyip commented Dec 9, 2020 •

edited

Loading

noahtallen commented Dec 9, 2020 •

edited

Loading

noahtallen commented Dec 9, 2020 •

edited

Loading

jeyip commented Dec 9, 2020

ajgagnon commented Dec 9, 2020

noahtallen commented Dec 9, 2020 •

edited

Loading

ajgagnon commented Dec 11, 2020

pbking commented Dec 16, 2020

wp-env: Xdebug support #27346

wp-env: Xdebug support #27346

Conversation

noahtallen commented Nov 28, 2020 • edited Loading

Description

How has this been tested?

Setup environment

IDE setup

Public API:

Other considerations:

noahtallen Nov 28, 2020

Choose a reason for hiding this comment

github-actions bot commented Nov 28, 2020 • edited Loading

derickr commented Dec 1, 2020

noahtallen commented Dec 2, 2020

noahtallen commented Dec 2, 2020

derickr commented Dec 3, 2020

jeyip commented Dec 7, 2020

jeyip commented Dec 7, 2020

jeyip commented Dec 8, 2020

jeyip commented Dec 8, 2020 • edited Loading

jeyip commented Dec 8, 2020

noahtallen commented Dec 8, 2020 • edited Loading

jeyip commented Dec 8, 2020

jeyip commented Dec 9, 2020 • edited Loading

noahtallen commented Dec 9, 2020

jeyip commented Dec 9, 2020 • edited Loading

jeyip commented Dec 9, 2020

noahtallen commented Dec 9, 2020

jeyip commented Dec 9, 2020

noahtallen commented Dec 9, 2020

jeyip commented Dec 9, 2020 • edited Loading

noahtallen commented Dec 9, 2020 • edited Loading

noahtallen commented Dec 9, 2020 • edited Loading

jeyip commented Dec 9, 2020

ajgagnon commented Dec 9, 2020

noahtallen commented Dec 9, 2020 • edited Loading

ajgagnon commented Dec 11, 2020

pbking commented Dec 16, 2020

noahtallen commented Nov 28, 2020 •

edited

Loading

github-actions bot commented Nov 28, 2020 •

edited

Loading

jeyip commented Dec 8, 2020 •

edited

Loading

noahtallen commented Dec 8, 2020 •

edited

Loading

jeyip commented Dec 9, 2020 •

edited

Loading

jeyip commented Dec 9, 2020 •

edited

Loading

jeyip commented Dec 9, 2020 •

edited

Loading

noahtallen commented Dec 9, 2020 •

edited

Loading

noahtallen commented Dec 9, 2020 •

edited

Loading

noahtallen commented Dec 9, 2020 •

edited

Loading