zhongwei/gh-emdashcodes-wp-ability-toolkit-claude-code-plugins-wp-env

Fork 0

Files

Zhongwei Li 121cc922c9 Initial commit

2025-11-29 18:25:40 +08:00

16 KiB

Raw Blame History

wp-env Command Reference

Complete reference for all wp-env commands, options, and environment variables.

Command Overview

Command	Description
`wp-env start`	Install and start the WordPress environment
`wp-env stop`	Stop the WordPress environment
`wp-env clean`	Clean the WordPress databases
`wp-env run`	Run arbitrary commands in containers
`wp-env destroy`	Destroy the WordPress environment completely
`wp-env logs`	Display PHP and Docker logs
`wp-env install-path`	Get the path where environment files are stored

wp-env start

Installs and initializes the WordPress environment, including downloading specified remote sources.

wp-env start [options]

Options

Option	Type	Default	Description
`--debug`	boolean	`false`	Enable debug output
`--update`	boolean	`false`	Download source updates and apply WordPress configuration
`--xdebug`	string	-	Enable Xdebug (see Xdebug section below)
`--spx`	string	-	Enable SPX profiling (see SPX section below)
`--scripts`	boolean	`true`	Execute any configured lifecycle scripts

Behavior

On first run: Downloads WordPress, creates containers, initializes environment
Subsequent runs: Starts existing environment without changes
With --update: Re-downloads sources and re-applies configuration (doesn't overwrite content)

Environment Variables

These environment variables override .wp-env.json settings:

Variable	Description	Example
`WP_ENV_PORT`	Development environment web server port	`WP_ENV_PORT=3333 wp-env start`
`WP_ENV_TESTS_PORT`	Testing environment web server port	`WP_ENV_TESTS_PORT=3334 wp-env start`
`WP_ENV_MYSQL_PORT`	MySQL port for development environment	`WP_ENV_MYSQL_PORT=13306 wp-env start`
`WP_ENV_TESTS_MYSQL_PORT`	MySQL port for testing environment	`WP_ENV_TESTS_MYSQL_PORT=13307 wp-env start`
`WP_ENV_PHPMYADMIN_PORT`	phpMyAdmin port for development	`WP_ENV_PHPMYADMIN_PORT=9001 wp-env start`
`WP_ENV_TESTS_PHPMYADMIN_PORT`	phpMyAdmin port for testing	`WP_ENV_TESTS_PHPMYADMIN_PORT=9002 wp-env start`
`WP_ENV_HOME`	Directory for wp-env files	`WP_ENV_HOME="./local" wp-env start`
`WP_ENV_CORE`	WordPress version/source	`WP_ENV_CORE="WordPress/WordPress#trunk" wp-env start`
`WP_ENV_PHP_VERSION`	PHP version to use	`WP_ENV_PHP_VERSION="8.0" wp-env start`
`WP_ENV_MULTISITE`	Enable multisite	`WP_ENV_MULTISITE=true wp-env start`

Note: Environment variables take precedence over .wp-env.json values.

Xdebug Support

Enable Xdebug for debugging PHP code:

# Enable with default "debug" mode
wp-env start --xdebug

# Enable with specific modes
wp-env start --xdebug=profile,trace,debug

# When using npm run (in local project dependencies)
npm run wp-env start -- --xdebug

Xdebug Modes:

debug - Step debugging (default when --xdebug is used)
develop - Development aids
coverage - Code coverage analysis
gcstats - Garbage collection statistics
profile - Profiling
trace - Function trace

See Xdebug documentation for mode details.

Requirements:

PHP version >= 7.2 (Xdebug won't install on legacy PHP versions)
IDE configuration for port 9003

IDE Configuration Example (VS Code):

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

SPX Profiling

SPX is a lightweight profiling extension with a built-in web UI:

# Enable SPX profiling
wp-env start --spx

# With specific mode
wp-env start --spx=enabled

Access SPX UI:

Development: http://localhost:8888/?SPX_KEY=dev&SPX_UI_URI=/
Testing: http://localhost:8889/?SPX_KEY=dev&SPX_UI_URI=/

SPX Features:

Flame graphs and performance metrics
Function call timelines
Memory usage analysis
Minimal performance overhead

See SPX documentation for details.

Examples

# Basic start
wp-env start

# Start with updates
wp-env start --update

# Start with custom port
WP_ENV_PORT=4000 wp-env start

# Start with Xdebug enabled
wp-env start --xdebug

# Start with multisite and custom PHP version
WP_ENV_MULTISITE=true WP_ENV_PHP_VERSION="8.1" wp-env start

# Start with debug output
wp-env start --debug

wp-env stop

Stops running WordPress containers and frees the ports.

wp-env stop [options]

Options

Option	Type	Default	Description
`--debug`	boolean	`false`	Enable debug output

Behavior

Stops all containers for the current project
Preserves all data (database, uploads, configuration)
Frees ports (8888, 8889, etc.)
Containers can be restarted with wp-env start

Example

wp-env stop

wp-env clean

Cleans (resets) WordPress databases.

wp-env clean [environment] [options]

Arguments

Argument	Choices	Default	Description
`environment`	`all`, `development`, `tests`	`tests`	Which environment's database to clean

Options

Option	Type	Default	Description
`--debug`	boolean	`false`	Enable debug output
`--scripts`	boolean	`true`	Execute any configured lifecycle scripts

Behavior

⚠️ Warning: Permanently deletes all posts, pages, media, users (except admin), and other WordPress content.

Resets database to fresh WordPress installation
Preserves WordPress core files and configuration
Keeps admin user (username: admin, password: password)

Examples

# Clean tests database only (default)
wp-env clean
wp-env clean tests

# Clean development database
wp-env clean development

# Clean both databases
wp-env clean all

wp-env run

Runs arbitrary commands in Docker containers.

wp-env run <container> <command> [options]

Arguments

Argument	Type	Description
`container`	string (required)	The Docker service to run the command on
`command`	string (required)	The command to run

Available Containers

Container	Description	Available Tools
`cli`	WP-CLI environment (development)	wp-cli, composer, phpunit, bash
`tests-cli`	WP-CLI environment (testing)	wp-cli, composer, phpunit, bash
`wordpress`	WordPress PHP environment (development)	php
`tests-wordpress`	WordPress PHP environment (testing)	php
`mysql`	MySQL database (development)	mysql
`tests-mysql`	MySQL database (testing)	mysql
`composer`	Composer environment	composer
`phpmyadmin`	phpMyAdmin (if enabled)	-

Options

Option	Type	Default	Description
`--debug`	boolean	`false`	Enable debug output
`--env-cwd`	string	`"."`	Working directory inside container (relative to WordPress root)

Working Directory

Default: WordPress root (/var/www/html)
Paths without leading slash are relative to WordPress root
Use --env-cwd for commands that need specific directory context

Argument Parsing

Commands with options that conflict with wp-env options require -- separator:

# This shows wp-env help (--help interpreted by wp-env)
wp-env run cli php --help

# This shows PHP help (--help passed to php)
wp-env run cli php -- --help

Examples

WP-CLI Commands

# List users
wp-env run cli wp user list

# Install and activate a plugin
wp-env run cli wp plugin install contact-form-7 --activate

# Create a post on tests instance
wp-env run tests-cli wp post create --post_title="Test" --post_status=publish

# Update permalink structure
wp-env run cli "wp rewrite structure /%postname%/"

# Open WordPress shell (interactive PHP)
wp-env run cli wp shell

Composer Commands

# Run composer install in a plugin directory
wp-env run cli --env-cwd=wp-content/plugins/your-plugin composer install

# Update dependencies
wp-env run cli --env-cwd=wp-content/plugins/your-plugin composer update

# Show installed packages
wp-env run cli --env-cwd=wp-content/plugins/your-plugin composer show

PHPUnit Commands

# Run tests in a plugin
wp-env run tests-cli --env-cwd=wp-content/plugins/your-plugin phpunit

# Run specific test file
wp-env run tests-cli --env-cwd=wp-content/plugins/your-plugin phpunit tests/test-sample.php

# Run with coverage
wp-env run tests-cli --env-cwd=wp-content/plugins/your-plugin phpunit --coverage-html coverage

Shell Access

# Open bash shell in CLI container
wp-env run cli bash

# Open bash in tests container
wp-env run tests-cli bash

# Run a bash script
wp-env run cli bash /var/www/html/wp-content/plugins/your-plugin/scripts/setup.sh

Direct PHP Execution

# Run PHP script
wp-env run cli php /var/www/html/wp-content/plugins/your-plugin/scripts/migrate.php

# Execute PHP code directly
wp-env run cli php -r "echo phpversion();"

wp-env destroy

Destroys the WordPress environment completely.

wp-env destroy [options]

Options

Option	Type	Default	Description
`--debug`	boolean	`false`	Enable debug output
`--scripts`	boolean	`true`	Execute any configured lifecycle scripts

Behavior

⚠️ Warning: Permanently deletes:

All Docker containers
All Docker volumes (databases, uploads, etc.)
All Docker networks
All local files in the wp-env home directory

Use this when:

Environment is corrupted beyond repair
Need to start completely fresh
Freeing up disk space
Removing wp-env from a project

Example

# Destroy everything
wp-env destroy

# Create fresh environment
wp-env start

wp-env logs

Displays PHP and Docker logs for the WordPress environment.

wp-env logs [environment] [options]

Arguments

Argument	Choices	Default	Description
`environment`	`development`, `tests`, `all`	`development`	Which environment to display logs from

Options

Option	Type	Default	Description
`--debug`	boolean	`false`	Enable debug output
`--watch`	boolean	`true`	Watch for logs as they happen (follow mode)

Behavior

Shows PHP error logs and Docker container logs
By default, follows/tails logs in real-time (press Ctrl+C to stop)
Use --watch=false to show current logs and exit

Examples

# View development logs (follows by default)
wp-env logs

# View testing environment logs
wp-env logs tests

# View both environments
wp-env logs all

# Show logs without following
wp-env logs --watch=false

# View with debug output
wp-env logs --debug

wp-env install-path

Gets the path where all environment files are stored.

wp-env install-path

Behavior

Returns the absolute path to the directory containing:

Docker files and configurations
Downloaded WordPress core
PHPUnit files
Downloaded plugins, themes, and other sources

Path Format

Default location: $WP_ENV_HOME/$md5_of_project_path
macOS/Windows default: ~/.wp-env/$md5_of_project_path
Linux default: ~/wp-env/$md5_of_project_path (for Snap compatibility)

Example

$ wp-env install-path
/home/user/.wp-env/63263e6506becb7b8613b02d42280a49

Global Options

Options available for all commands:

Option	Type	Default	Description
`--debug`	boolean	`false`	Enable debug output for troubleshooting
`--help`	boolean	`false`	Show help for the command
`--version`	boolean	`false`	Show wp-env version number

Lifecycle Scripts

Lifecycle scripts run automatically at certain points. Configure in .wp-env.json:

{
  "lifecycleScripts": {
    "afterStart": "node scripts/setup-e2e.js",
    "afterClean": "echo 'Database cleaned'",
    "afterDestroy": "rm -rf custom-cache"
  }
}

Available Lifecycle Events

Event	When It Runs	Use Cases
`afterStart`	After `wp-env start` completes	Bootstrap data, run migrations, configure environment
`afterClean`	After `wp-env clean` completes	Log cleanup, reset custom data
`afterDestroy`	After `wp-env destroy` completes	Clean up external resources

Environment Variable Override

Override lifecycle scripts via environment variables:

WP_ENV_LIFECYCLE_SCRIPT_AFTER_START="npm run bootstrap" wp-env start

Format: WP_ENV_LIFECYCLE_SCRIPT_{EVENT_NAME} (uppercase, snake_case)

Exit Codes

All wp-env commands use standard exit codes:

Code	Meaning
`0`	Success
`1`	Error (see error message for details)

Tips and Best Practices

Using with npm Scripts

Add wp-env commands to package.json for convenience:

{
  "scripts": {
    "wp-env": "wp-env",
    "env:start": "wp-env start",
    "env:stop": "wp-env stop",
    "env:clean": "wp-env clean all && wp-env start",
    "env:reset": "wp-env destroy && wp-env start",
    "wp": "wp-env run cli wp",
    "composer": "wp-env run cli --env-cwd=wp-content/plugins/your-plugin composer",
    "test": "wp-env run tests-cli --env-cwd=wp-content/plugins/your-plugin phpunit"
  }
}

Then use: npm run env:start, npm run test, etc.

Passing Flags to npm Scripts

When using npm run wp-env, use -- to pass flags:

# Wrong: --update goes to npm, not wp-env
npm run env:start --update

# Right: --update passed to wp-env
npm run env:start -- --update

Command Chaining

Chain commands for complex workflows:

# Reset and start fresh
wp-env clean all && wp-env start

# Destroy, recreate, and install a plugin
wp-env destroy && wp-env start && wp-env run cli wp plugin install woocommerce --activate

Checking Environment Status

Verify wp-env is running properly:

# Check running containers
docker ps

# Should show three containers by default:
# - wordpress (port 8888)
# - tests-wordpress (port 8889)
# - mariadb (port 3306)

# Check wp-env version
wp-env --version

# View install path
wp-env install-path

Working with Multiple Projects

Each project has its own isolated environment:

# Project 1
cd ~/projects/plugin-a
wp-env start  # Uses port 8888

# Project 2 (different port)
cd ~/projects/plugin-b
WP_ENV_PORT=4000 wp-env start  # Uses port 4000

WordPress PHPUnit Tests

wp-env includes WordPress' PHPUnit test files automatically.

Environment Variable

WP_TESTS_DIR - Points to PHPUnit test files location within containers
Files correspond to the installed WordPress version

Custom wp-tests-config.php

Override the default test configuration:

// In your bootstrap.php file
define('WP_TESTS_CONFIG_FILE_PATH', '/path/to/custom/wp-tests-config.php');

WordPress will use your custom file instead of the default.

Running Tests

# Run all tests
wp-env run tests-cli --env-cwd=wp-content/plugins/your-plugin phpunit

# Run specific test file
wp-env run tests-cli --env-cwd=wp-content/plugins/your-plugin phpunit tests/test-sample.php

# Run with bootstrap file
wp-env run tests-cli --env-cwd=wp-content/plugins/your-plugin phpunit --bootstrap=tests/bootstrap.php

Database Access

Direct database access credentials:

Environment	Host	Port	User	Password	Database
Development	`localhost`	`WP_ENV_MYSQL_PORT` (random if not set)	`root`	`password`	`wordpress`
Testing	`localhost`	`WP_ENV_TESTS_MYSQL_PORT` (random if not set)	`root`	`password`	`wordpress-tests`

Note: MySQL ports are not exposed by default. Set WP_ENV_MYSQL_PORT or WP_ENV_TESTS_MYSQL_PORT to expose them.

Connecting with MySQL Client

# Expose MySQL port first
WP_ENV_MYSQL_PORT=13306 wp-env start

# Connect from host
mysql -h 127.0.0.1 -P 13306 -u root -ppassword wordpress

Using phpMyAdmin

# Enable phpMyAdmin on port 9001
WP_ENV_PHPMYADMIN_PORT=9001 wp-env start

# Access at http://localhost:9001
# Login: root / password

Or configure in .wp-env.json:

{
  "phpmyadminPort": 9001
}

16 KiB Raw Blame History

wp-env Command Reference

Command Overview

wp-env start

Options

Behavior

Environment Variables

Xdebug Support

SPX Profiling

Examples

wp-env stop

Options

Behavior

Example

wp-env clean

Arguments

Options

Behavior

Examples

wp-env run

Arguments

Available Containers

Options

Working Directory

Argument Parsing

Examples

WP-CLI Commands

Composer Commands

PHPUnit Commands

Shell Access

Direct PHP Execution

wp-env destroy

Options

Behavior

Example

wp-env logs

Arguments

Options

Behavior

Examples

wp-env install-path

Behavior

Path Format

Example

Global Options

Lifecycle Scripts

Available Lifecycle Events

Environment Variable Override

Exit Codes

Tips and Best Practices

Using with npm Scripts

Passing Flags to npm Scripts

Command Chaining

Checking Environment Status

Working with Multiple Projects

WordPress PHPUnit Tests

Environment Variable

Custom wp-tests-config.php

Running Tests

Database Access

Connecting with MySQL Client

Using phpMyAdmin

16 KiB

Raw Blame History