Skip to content

Conversation

@brandonpayton
Copy link
Member

@brandonpayton brandonpayton commented Oct 29, 2025

Motivation for the change, related issues

Today, Playground enables Xdebug during boot which may be surprising to users. If the debugger breaks at the first line, the user will be debugging the Playground boot process. Let's skip this by default and consider adding a command line flag to enable boot-time Xdebug breaks.

Implementation details

A big change in this PR is that the first Playground worker is now only used during boot. We discard it after that boot and setup process completes. Some positive consequences of this change are:

  • Reflects the truth that the Playground worker has special configuration and responsibilities as part of the boot process.
  • Allows us to be clear that all post-boot workers are based on the same configuration and truth. There is no remaining special boot-time worker that might behave differently from the others.
  • Allows us to control whether the boot-and-setup worker has Xdebug enabled separately from the regular workers.

Testing Instructions (or ideally a Blueprint)

Before checking out this branch:

  • Create a local directory at the top level of your Playground working dir that can be mounted as /wordpress
  • Run npx nx unbuilt-asyncify playground-cli -- server --mount-dir <local-dir> /wordpress so Playground will download and install WordPress in your local directory.
  • Open the local directory as a project root in Visual Studio Code, select the debug pane, and create a launch.json file containing the following configuration:
    {
        "name": "PR test for WP Playground CLI - Listen for Xdebug",
        "type": "php",
        "request": "launch",
        "port": 9003,
        "pathMappings": {
            "/": "${workspaceFolder}/.playground-xdebug-root",
            "/wordpress": "${workspaceFolder}/"
        },
        "stopOnEntry": true,
    }
    
  • Start the "PR test for WP Playground CLI - Listen for Xdebug" debug target within vscode
  • cd into the local WP dir and run the following command and confirm that vscode hit a breakpoint before the "WordPress is running on http://127.0.0.1:9400" message is printed:
    node --experimental-strip-types --experimental-transform-types --disable-warning=ExperimentalWarning --import ../packages/meta/src/node-es-module-loader/register.mts ../packages/playground/cli/src/cli.ts server --auto-mount=. --verbosity=debug --skip-wordpress-setup --xdebug --experimental-unsafe-ide-integration --php=8.3 --experimental-multi-worker=4

After checking out this branch:

  • Open the previously created local WP dir as the workspace root within vscode
  • Run the "PR test for WP Playground CLI - Listen for Xdebug" debug target
  • cd into the local WP dir, re-run the above node command, and confirm that no breakpoint was hit during the boot process.

@brandonpayton brandonpayton requested a review from a team October 29, 2025 03:33
@brandonpayton brandonpayton self-assigned this Oct 29, 2025
@brandonpayton brandonpayton added [Type] Bug An existing feature does not function as intended [Package][@wp-playground] CLI XDebug labels Oct 29, 2025
@brandonpayton
Copy link
Member Author

It looks like Xdebug support relies upon being set up in the initial worker. Currently, this PR breaks the Xdebug feature. Will look at fixing that.

@brandonpayton
Copy link
Member Author

It looks like Xdebug support relies upon being set up in the initial worker. Currently, this PR breaks the Xdebug feature. Will look at fixing that.

It turns out that, even though we were relaying the --xdebug option when creating subsequent workers, the boot function for the v1 workers was only using the xdebug flag for the initial worker. This is now fixed.

The v2 worker appears to consider the xdebug flag for both initial and subsequent workers.

@brandonpayton
Copy link
Member Author

This is almost ready. There are a few remaining test failures, and I'm looking at those.

@brandonpayton
Copy link
Member Author

It turns out that using a using a pool of non-initial workers revealed some bugs like:

  • PHP Version wasn't being respected by the Blueprints v1 handler, except for the initial worker. It looks like this happened when we adjusted Blueprint v1 resolution. It worked for the primary worker but wasn't fully wired for subsequent workers.
  • The v1 followSymlinks flag wasn't being properly passed to non-primary workers.

These are now fixed, and the tests are passing again.

I think this is ready for review. Note, this PR includes some cleanup-related refactor from #2836, and it would probably make more sense to review that one before this one.

@brandonpayton brandonpayton marked this pull request as ready for review October 30, 2025 03:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Package][@wp-playground] CLI [Type] Bug An existing feature does not function as intended XDebug

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants