Add phpMyAdmin support to wp-env Playground runtime (#75532)

youknowriad · t-hamano · scruffian · commit 65ec5013e04f · 2026-02-23T17:21:35.000Z
Co-authored-by: youknowriad &lt;youknowriad@git.wordpress.org&gt;
Co-authored-by: t-hamano &lt;wildworks@git.wordpress.org&gt;
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/env/CHANGELOG.md b/packages/env/CHANGELOG.md
@@ -16,6 +16,8 @@
 
 ### New Features
 
+-   Added `phpmyadmin` boolean configuration option to enable phpMyAdmin. Setting `phpmyadminPort` also enables phpMyAdmin for backward compatibility.
+-   Added phpMyAdmin support to the Playground runtime. When enabled, phpMyAdmin is available at `http://localhost:<port>/phpmyadmin`.
 -   Added `status` command that shows comprehensive environment information including running state, URLs, ports, configuration, and paths.
 -   Added `--config` global option to specify a custom configuration file path, enabling multiple parallel environments from the same directory.
 -   Added `testsEnvironment` configuration option. Set to `false` to skip creating test containers (`tests-mysql`, `tests-wordpress`, `tests-cli`, `tests-phpmyadmin`), reducing resource usage when test isolation is achieved via separate config files.
diff --git a/packages/env/README.md b/packages/env/README.md
@@ -41,7 +41,7 @@ $ wp-env start --runtime=playground
 | Requires Docker | Yes | No |
 | Xdebug | Yes | Yes |
 | SPX profiling | Yes | No |
-| phpMyAdmin | Yes | No |
+| phpMyAdmin | Yes | Yes |
 | MySQL database | Yes | No (SQLite) |
 | Multisite | Yes | Yes |
 | Custom PHP version | Yes | Yes |
@@ -596,7 +596,8 @@ You can customize the WordPress installation, plugins and themes that the develo
 | `"config"`           | `Object`       | See below.                             | Mapping of wp-config.php constants to their desired values.                                                                      |
 | `"mappings"`         | `Object`       | `"{}"`                                 | Mapping of WordPress directories to local directories to be mounted in the WordPress instance.                                   |
 | `"mysqlPort"`        | `integer`      | `null` (randomly assigned)             | The MySQL port number to expose.                                                                                                 |
-| `"phpmyadminPort"`   | `integer`      | `null`                                 | The port number for phpMyAdmin. If provided, you'll access phpMyAdmin through: http://localhost:<port>                           |
+| `"phpmyadmin"`       | `boolean`      | `false`                                | Whether to enable phpMyAdmin for database management.                                                                            |
+| `"phpmyadminPort"`   | `integer`      | `null` (randomly assigned)             | The port number for phpMyAdmin (Docker only). Setting this also enables phpMyAdmin.                                              |
 | `"multisite"`        | `boolean`      | `false`                                | Whether to set up a multisite installation.                                                                                      |
 | `"lifecycleScripts"` | `Object`       | `"{}"`                                 | Mapping of commands that should be executed at certain points in the lifecycle.                                                   |
 
@@ -785,7 +786,7 @@ You can tell `wp-env` to use a custom port number so that your instance does not
 These can also be set via environment variables:
 
 - `WP_ENV_PORT` to override the web server's port.
-- phpMyAdmin is not enabled by default, but its port can also be overridden via `WP_ENV_PHPMYADMIN_PORT`.
+- phpMyAdmin is not enabled by default. Enable it with `"phpmyadmin": true` in `.wp-env.json`. The Docker runtime port can also be overridden via `WP_ENV_PHPMYADMIN_PORT`.
 - By default, MySQL isn't exposed to the host, which means no chance of port conflicts. But this can also be overridden via `WP_ENV_MYSQL_PORT`.
 
 ### Specific PHP Version
diff --git a/packages/env/lib/config/parse-config.js b/packages/env/lib/config/parse-config.js
@@ -51,7 +51,8 @@ const mergeConfigs = require( './merge-configs' );
  * @property {WPSource[]}                themeSources   Themes to load in the environment.
  * @property {number}                    port           The port to use.
  * @property {number}                    mysqlPort      The port to use for MySQL. Random if empty.
- * @property {number}                    phpmyadminPort The port to use for phpMyAdmin. If empty, disabled phpMyAdmin.
+ * @property {boolean}                   phpmyadmin     Whether to enable phpMyAdmin.
+ * @property {number}                    phpmyadminPort The port to use for phpMyAdmin. Random if empty.
  * @property {boolean}                   multisite      Whether to set up a multisite installation.
  * @property {Object}                    config         Mapping of wp-config.php constants to their desired values.
  * @property {Object.<string, WPSource>} mappings       Mapping of WordPress directories to local directories which should be mounted.
@@ -89,6 +90,7 @@ const DEFAULT_ENVIRONMENT_CONFIG = {
 	port: 8888,
 	testsPort: 8889,
 	mysqlPort: null,
+	phpmyadmin: false,
 	phpmyadminPort: null,
 	multisite: false,
 	mappings: {},
@@ -306,6 +308,7 @@ function getEnvironmentVarOverrides( cacheDirectoryPath ) {
 	if ( overrides.phpmyadminPort ) {
 		overrideConfig.env.development.phpmyadminPort =
 			overrides.phpmyadminPort;
+		overrideConfig.env.development.phpmyadmin = true;
 	}
 
 	if ( overrides.testsPort ) {
@@ -496,8 +499,17 @@ async function parseEnvironmentConfig(
 		parsedConfig.mysqlPort = config.mysqlPort;
 	}
 
+	if ( config.phpmyadmin !== undefined ) {
+		parsedConfig.phpmyadmin = config.phpmyadmin;
+	}
+
 	if ( config.phpmyadminPort !== undefined ) {
 		parsedConfig.phpmyadminPort = config.phpmyadminPort;
+		// Backward compat: setting phpmyadminPort implies phpmyadmin: true
+		// unless phpmyadmin was explicitly set.
+		if ( config.phpmyadmin === undefined ) {
+			parsedConfig.phpmyadmin = true;
+		}
 	}
 
 	if ( config.multisite !== undefined ) {
diff --git a/packages/env/lib/config/test/__snapshots__/config-integration.js.snap b/packages/env/lib/config/test/__snapshots__/config-integration.js.snap
@@ -33,6 +33,7 @@ exports[`Config Integration should load local and override configuration files 1
       "multisite": false,
       "mysqlPort": 23306,
       "phpVersion": null,
+      "phpmyadmin": false,
       "phpmyadminPort": null,
       "pluginSources": [],
       "port": 999,
@@ -64,6 +65,7 @@ exports[`Config Integration should load local and override configuration files 1
       "multisite": false,
       "mysqlPort": 23307,
       "phpVersion": null,
+      "phpmyadmin": false,
       "phpmyadminPort": null,
       "pluginSources": [],
       "port": 456,
@@ -116,6 +118,7 @@ exports[`Config Integration should load local configuration file 1`] = `
       "multisite": false,
       "mysqlPort": 13306,
       "phpVersion": null,
+      "phpmyadmin": false,
       "phpmyadminPort": null,
       "pluginSources": [],
       "port": 123,
@@ -147,6 +150,7 @@ exports[`Config Integration should load local configuration file 1`] = `
       "multisite": false,
       "mysqlPort": 23307,
       "phpVersion": null,
+      "phpmyadmin": false,
       "phpmyadminPort": null,
       "pluginSources": [],
       "port": 8889,
@@ -199,6 +203,7 @@ exports[`Config Integration should use default configuration 1`] = `
       "multisite": false,
       "mysqlPort": null,
       "phpVersion": null,
+      "phpmyadmin": false,
       "phpmyadminPort": null,
       "pluginSources": [],
       "port": 8888,
@@ -230,6 +235,7 @@ exports[`Config Integration should use default configuration 1`] = `
       "multisite": false,
       "mysqlPort": null,
       "phpVersion": null,
+      "phpmyadmin": false,
       "phpmyadminPort": null,
       "pluginSources": [],
       "port": 8889,
@@ -282,6 +288,7 @@ exports[`Config Integration should use environment variables over local and over
       "multisite": false,
       "mysqlPort": 23306,
       "phpVersion": null,
+      "phpmyadmin": false,
       "phpmyadminPort": null,
       "pluginSources": [],
       "port": 12345,
@@ -314,6 +321,7 @@ exports[`Config Integration should use environment variables over local and over
       "multisite": false,
       "mysqlPort": 23307,
       "phpVersion": null,
+      "phpmyadmin": false,
       "phpmyadminPort": null,
       "pluginSources": [],
       "port": 61234,
diff --git a/packages/env/lib/config/test/parse-config.js b/packages/env/lib/config/test/parse-config.js
@@ -22,6 +22,7 @@ const DEFAULT_CONFIG = {
 	port: 8888,
 	testsPort: 8889,
 	mysqlPort: null,
+	phpmyadmin: false,
 	phpmyadminPort: null,
 	multisite: false,
 	phpVersion: null,
@@ -416,6 +417,7 @@ describe( 'parseConfig', () => {
 					},
 					env: {
 						development: {
+							phpmyadmin: true,
 							phpmyadminPort: 9001,
 						},
 					},
@@ -428,6 +430,38 @@ describe( 'parseConfig', () => {
 		const expected = {
 			development: {
 				...DEFAULT_CONFIG.env.development,
+				phpmyadmin: true,
+				phpmyadminPort: 9001,
+			},
+			tests: DEFAULT_CONFIG.env.tests,
+		};
+		expect( parsed.env ).toEqual( expected );
+	} );
+
+	it( 'should infer phpmyadmin: true when phpmyadminPort is set', async () => {
+		readRawConfigFile.mockImplementation( async ( configFile ) => {
+			if ( configFile === '/test/gutenberg/.wp-env.json' ) {
+				return {
+					core: 'WordPress/WordPress#Test',
+					phpVersion: '1.0',
+					lifecycleScripts: {
+						afterStart: 'test',
+					},
+					env: {
+						development: {
+							phpmyadminPort: 9001,
+						},
+					},
+				};
+			}
+		} );
+
+		const parsed = await parseConfig( '/test/gutenberg', '/cache' );
+
+		const expected = {
+			development: {
+				...DEFAULT_CONFIG.env.development,
+				phpmyadmin: true,
 				phpmyadminPort: 9001,
 			},
 			tests: DEFAULT_CONFIG.env.tests,
diff --git a/packages/env/lib/runtime/docker/index.js b/packages/env/lib/runtime/docker/index.js
@@ -241,7 +241,7 @@ class DockerRuntime {
 				: [],
 		} );
 
-		if ( fullConfig.env.development.phpmyadminPort ) {
+		if ( fullConfig.env.development.phpmyadmin ) {
 			await dockerCompose.upOne( 'phpmyadmin', {
 				...dockerComposeConfig,
 				commandOptions: shouldConfigureWp
@@ -250,7 +250,7 @@ class DockerRuntime {
 			} );
 		}
 
-		if ( testsEnabled && fullConfig.env.tests.phpmyadminPort ) {
+		if ( testsEnabled && fullConfig.env.tests.phpmyadmin ) {
 			await dockerCompose.upOne( 'tests-phpmyadmin', {
 				...dockerComposeConfig,
 				commandOptions: shouldConfigureWp
@@ -312,7 +312,7 @@ class DockerRuntime {
 			dockerComposeConfig
 		);
 
-		const phpmyadminPort = fullConfig.env.development.phpmyadminPort
+		const phpmyadminPort = fullConfig.env.development.phpmyadmin
 			? await this._getPublicDockerPort(
 					'phpmyadmin',
 					80,
@@ -335,7 +335,7 @@ class DockerRuntime {
 				3306,
 				dockerComposeConfig
 			);
-			const testsPhpmyadminPort = fullConfig.env.tests.phpmyadminPort
+			const testsPhpmyadminPort = fullConfig.env.tests.phpmyadmin
 				? await this._getPublicDockerPort(
 						'tests-phpmyadmin',
 						80,
@@ -726,7 +726,7 @@ class DockerRuntime {
 			);
 			isRunning = true;
 
-			if ( fullConfig.env.development.phpmyadminPort ) {
+			if ( fullConfig.env.development.phpmyadmin ) {
 				phpmyadminPort = await this._getPublicDockerPort(
 					'phpmyadmin',
 					80,
diff --git a/packages/env/lib/runtime/playground/index.js b/packages/env/lib/runtime/playground/index.js
@@ -48,7 +48,7 @@ class PlaygroundRuntime {
 			testsEnvironment: false, // Single environment only
 			xdebug: true, // Supported via --xdebug flag
 			spx: false, // Not supported in WebAssembly
-			phpMyAdmin: false, // Supported on playground.wordpress.net but not in CLI yet
+			phpMyAdmin: true, // Supported via --phpmyadmin CLI flag
 			multisite: true, // Supported via Blueprint
 			customPhpVersion: true, // Supported via --php flag
 			persistentDatabase: false, // Could be supported via mounts (not yet implemented)
@@ -170,6 +170,10 @@ class PlaygroundRuntime {
 			cliArgs.push( '--verbosity', 'debug' );
 		}
 
+		if ( envConfig.phpmyadmin ) {
+			cliArgs.push( '--phpmyadmin' );
+		}
+
 		if ( xdebug ) {
 			cliArgs.push( '--xdebug' );
 		}
@@ -184,12 +188,27 @@ class PlaygroundRuntime {
 		// Create write stream for log file
 		const logFileStream = await fs.open( logFile, 'w' );
 
+		// Resolve the CLI binary directly so that it is found even when
+		// the package is nested inside workspace node_modules (where npx
+		// cannot discover it).
+		const cliPackageJson = require.resolve(
+			'@wp-playground/cli/package.json'
+		);
+		const cliEntryPoint = path.join(
+			path.dirname( cliPackageJson ),
+			'wp-playground.js'
+		);
+
 		return new Promise( ( resolve, reject ) => {
-			const child = spawn( 'npx', [ '@wp-playground/cli', ...cliArgs ], {
-				detached: true,
-				stdio: [ 'ignore', logFileStream.fd, logFileStream.fd ],
-				env: { ...process.env, FORCE_COLOR: '0' },
-			} );
+			const child = spawn(
+				process.execPath,
+				[ cliEntryPoint, ...cliArgs ],
+				{
+					detached: true,
+					stdio: [ 'ignore', logFileStream.fd, logFileStream.fd ],
+					env: { ...process.env, FORCE_COLOR: '0' },
+				}
+			);
 
 			// Store child process reference
 			this.serverProcess = child;
@@ -241,8 +260,17 @@ class PlaygroundRuntime {
 				.then( async () => {
 					spinner.text = `WordPress Playground started at ${ siteUrl }`;
 
-					const message =
-						'WordPress development site started at ' + siteUrl;
+					const phpmyadminUrl = envConfig.phpmyadmin
+						? `${ siteUrl }/phpmyadmin`
+						: null;
+
+					const message = [
+						'WordPress development site started at ' + siteUrl,
+						phpmyadminUrl &&
+							`phpMyAdmin started at ${ phpmyadminUrl }`,
+					]
+						.filter( Boolean )
+						.join( '\n' );
 
 					resolve( {
 						message,
@@ -449,6 +477,10 @@ class PlaygroundRuntime {
 			runtime: 'playground',
 			urls: {
 				development: isRunning ? `http://localhost:${ port }` : null,
+				phpmyadmin:
+					isRunning && envConfig.phpmyadmin
+						? `http://localhost:${ port }/phpmyadmin`
+						: null,
 			},
 			ports: {
 				development: port,
diff --git a/packages/env/package.json b/packages/env/package.json
@@ -44,7 +44,7 @@
 	},
 	"dependencies": {
 		"@inquirer/prompts": "^7.2.0",
-		"@wp-playground/cli": "^3.0.0",
+		"@wp-playground/cli": "^3.0.48",
 		"chalk": "^4.0.0",
 		"copy-dir": "^1.3.0",
 		"cross-spawn": "^7.0.6",
diff --git a/schemas/json/wp-env.json b/schemas/json/wp-env.json
@@ -63,8 +63,13 @@
 					"type": "object",
 					"default": {}
 				},
+				"phpmyadmin": {
+					"description": "Whether to enable phpMyAdmin for database management.",
+					"type": "boolean",
+					"default": false
+				},
 				"phpmyadminPort": {
-					"description": "The port number to access phpMyAdmin.",
+					"description": "The port number to access phpMyAdmin. Setting this also enables phpMyAdmin.",
 					"type": "integer"
 				},
 				"multisite": {
@@ -82,6 +87,7 @@
 				"port",
 				"config",
 				"mappings",
+				"phpmyadmin",
 				"phpmyadminPort",
 				"multisite"
 			]
