The next release of the Contributor Toolkit adds step debugging with Xdebug. Set a breakpoint, load the page, and walk through Core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. one line at a time. It’s in beta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. now, and it needs your help before it ships.
The plan is for the WP Credits program to recommend the Contributor Toolkit as the primary way to contribute to WordPress. That isn’t in place yet, but its developer track already asks students to set up Xdebug. If the toolkit is going to be the tool those students use, it has to handle that step too. Both official environments, wordpress-develop’s Docker setup and wp-env, already offer Xdebug as an option, so this brings the toolkit in line with them.
Grab 2.1.0-beta.1 from its release page, turn on Xdebug, and try to hit a breakpoint. It has to work on macOS (Apple Silicon), Windows and Linux, in every editor the Xdebug setup covers, before it goes into a stable release. That’s a lot of combinations for a handful of maintainers to cover, so the more people who try it, the better. Testing runs until Friday, December 4. Anything reported after that will still be read, but it may not make it into the stable release.
While you’re in there, try the new code editor setting too. The editor you pick changes what the Xdebug setup shows you, so the two are worth testing together.
Step debugging with Xdebug
PHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher in a Contributor Toolkit site runs inside WordPress Playground, so there’s no php.ini to edit and no extension to install. Instead, there’s a setting.
- Turn it on: Settings → Sites → Step debugging (Xdebug). It’s off by default because it slows down every request, and like the PHP version setting, it takes effect the next time you start the server.
- Set up your editor: once the server is running with Xdebug, the site’s Debugging row offers a setup for VS Code, Cursor, PhpStorm or Zed. Each one has the steps and the config to copy, such as a launch.json JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. for VS Code or the host, port and path mapping for PhpStorm. If you already picked an editor in Settings, the button goes straight to that editor’s setup instead (more on that below).
- One site at a time: Playground always uses port 9003, so only one running site can have Xdebug. If you start a second one, the app tells you which site has it and what to do.
- You can cancel a start now: while the server starts, the button reads Cancel instead of a grayed-out “Starting…”. With Xdebug on, a breakpoint can catch Playground’s own startup requests, so you’ll want this.
The full walkthrough is in the new Step debugging with Xdebug guide. It goes live on the documentation site with the stable release so images may appear broken in GitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. https://github.com/.
Pick your code editor
You can now pick the code editor you use and save it as a setting, under Settings → General → Applications → Code editor. Once it’s set, the site menu’s Open in uses that editor, and clicking a file under Changed files opens it there too. If you haven’t picked one, or leave it on Ask each time (the default), the app asks you to choose from the editors installed on your computer.
The same setting changes the Xdebug setup. With VS Code, Cursor, PhpStorm or Zed chosen, the site’s Debugging row shows a single Set up Xdebug for Zed button (or whichever editor you picked) that opens that editor’s setup directly. With Ask each time, or an editor that has no Xdebug setup, such as Sublime Text, you get a menu of the editors the app finds instead.
What to test
Xdebug is the big one. Try whatever combination you have: macOS, Windows or Linux, with VS Code, Cursor, PhpStorm or Zed, on a Core or a Gutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc.
https://wordpress.org/gutenberg/ site. If you’re on Windows, your test is especially useful, since paths there are handled differently from macOS and Linux.
- Xdebug: turn on the setting, restart the server, follow the setup for your editor, and set a breakpoint in a Core file (say wp-login.php). Make sure that the editor stops on it. Try it on a Gutenberg site too, and try starting two sites at once.
- Code editor: pick your editor in Settings and click a file under Changed files. Check that the Debugging row’s Xdebug button names your editor. Then set the setting back to Ask each time and try both again.
If something breaks, or works but confuses you, please open an issue on GitHub. Include your platform and what you clicked, and attach the app log (Help → Open App Log) if you can.
If it just works, say so in the comments, with your platform and editor. A report that it worked on your setup helps too, because it shows which combinations are covered.
Problems found during the beta get fixed before WP Credits starts sending students to the toolkit. The user guide on trunk covers every feature here if you want more detail before you start.
Props to @greenshady and @psykro or review and feedback.
+make.wordpress.org/playground/ +make.wordpress.org/test/ +make.wordpress.org/community/
#contributor-day, #contributor-toolkit, #playground, #wordcamp