Wp Environments

WordPress Environment Detection & Configuration

This skill teaches how to detect the local development environment, read project configuration, select the correct WP-CLI wrapper, generate config files from templates, and manage PHP versions. It applies whenever a user requests environment setup or when a .wp-create.json manifest is present in the project root.

When This Skill Applies

• User requests WordPress environment setup, creation, or configuration
• A .wp-create.json file exists in the project root
• User asks about Docker, native server, DDEV, Lando, or wp-env setup
• User asks about PHP version management or web server configuration

1. Environment Detection

Run the detection script to discover what tools are available on the system:

bin/wp-env-setup.sh detect

This outputs JSON to stdout. Parse it to understand what is available. The full output structure:

{
  "os": "fedora",
  "package_manager": "dnf",
  "web_servers": {
    "nginx": { "installed": true, "version": "1.24.0", "running": true },
    "apache": { "installed": true, "version": "2.4.58", "running": false },
    "caddy": { "installed": false }
  },
  "php": {
    "versions": ["8.2", "8.3"],
    "active": "8.3",
    "extensions": ["mysql", "curl", "mbstring", "xml", "gd", "zip", "intl"]
  },
  "docker": {
    "installed": true,
    "version": "24.0.7",
    "compose": true
  },
  "tools": {
    "ddev": { "installed": false },
    "lando": { "installed": false },
    "wp-env": { "installed": false },
    "wp-cli": { "installed": true, "version": "2.9.0" }
  },
  "database": {
    "mariadb": { "installed": true, "version": "10.11", "running": true },
    "mysql": { "installed": false }
  }
}

Use this output to:

• Present available environment options to the user
• Auto-select the best environment type when the user does not specify
• Determine which web servers, PHP versions, and database engines are ready

2. Project Manifest: .wp-create.json

The .wp-create.json file is the single source of truth for all commands, agents, and skills. It is generated by /wp-create at the project root.

Full Manifest Structure

{
  "project": {
    "name": "My Project",
    "slug": "my-project",
    "domain": "my-project.local.com",
    "path": "/var/www/html/my-project",
    "created": "2026-03-15"
  },
  "environment": {
    "type": "docker",
    "engine": "docker-compose",
    "web_server": "nginx",
    "php_version": "8.3",
    "container_prefix": "my-project"
  },
  "database": {
    "name": "wp_my_project",
    "user": "root",
    "password": "root",
    "host": "db"
  },
  "wordpress": {
    "version": "latest",
    "admin_user": "webmaster",
    "admin_email": "webmaster@local.com",
    "url": "https://my-project.local.com",
    "permalink_structure": "/%postname%/"
  },
  "languages": {
    "primary": "en",
    "additional": ["es"],
    "default": "en"
  },
  "plugins": {
    "profile": "starter",
    "installed": [
      "secure-custom-fields",
      "wordpress-seo",
      "wp-fastest-cache"
    ]
  },
  "theme": {
    "slug": "my-project",
    "initialized": false
  },
  "wp_cli": {
    "wrapper": "docker exec my-project-wp wp --allow-root",
    "path_flag": ""
  }
}

Reading the Manifest

Always check for .wp-create.json at the project root before executing WP-CLI commands. If it exists, read wp_cli.wrapper and use it as the command prefix (referred to as $WP throughout this project).

If .wp-create.json does not exist, commands and agents work without WP-CLI integration -- no breaking changes to existing workflows.

3. WP-CLI Wrapper Selection

The wp_cli.wrapper field determines how WP-CLI commands are executed. Every agent reads this value and prepends it to all wp commands.

Usage Pattern

# Read wrapper from manifest
WP=$(jq -r '.wp_cli.wrapper' .wp-create.json)

# Use it for all WP-CLI operations
$WP core version
$WP plugin list --format=table
$WP option update blogname "My Site"

Never hardcode the execution method. Always read from the manifest.

4. Template Placeholder Replacement

All template files (.tpl extension) use {{placeholder}} syntax. No template engine is needed -- simple string replacement.

Process

1. Read the .tpl file
2. Replace every {{placeholder}} with the corresponding value from .wp-create.json or the detection output
3. Write the result to the final config file path (without the .tpl extension)

Example

Given templates/native/nginx.conf.tpl containing:

server {
    listen 443 ssl;
    server_name {{domain}};
    root {{document_root}};

    ssl_certificate {{ssl_cert}};
    ssl_certificate_key {{ssl_key}};

    location ~ \.php$ {
        fastcgi_pass unix:{{php_fpm_sock}};
    }
}

Replace placeholders with values from the manifest to produce the final nginx config.

Common Placeholders

Mapping Placeholders to Manifest Fields

5. Docker Port Conflict Detection

Before starting Docker containers, check for port conflicts. Default ports used by the stack:

• 80/443 -- Web server (HTTP/HTTPS)
• 3306 -- MariaDB/MySQL
• 8080 -- phpMyAdmin
• 8025 -- Mailpit

Detection Commands

# Linux — check listening ports
ss -tlnp | grep ':80 \|:443 \|:3306 \|:8080 \|:8025 '

# macOS or fallback
lsof -i :80 -i :443 -i :3306 -i :8080 -i :8025

Conflict Resolution

If a port is in use:

1. Identify which process holds the port
2. Offer the user alternatives:
   • Stop the conflicting service
   • Assign a different port (e.g., 8081 instead of 8080)
3. Update the manifest and generated config files with the alternative port

6. PHP Version Management

Native Environments

PHP version management depends on the OS detected by bin/wp-env-setup.sh detect:

Use bin/wp-env-setup.sh php-list to see available PHP versions before attempting installation.

Use bin/wp-env-setup.sh php-install --version=8.3 to install a new version (requires sudo).

Docker Environments

For Docker-based environments, PHP version is controlled by the container image tag in the template:

# In docker-compose.yml.tpl
services:
  wordpress:
    image: wordpress:php{{php_version}}-fpm

No system-level PHP installation is needed. Change the environment.php_version value in .wp-create.json and regenerate the Docker config from the template.

DDEV / Lando

These tools manage PHP internally:

• DDEV: Set php_version in .ddev/config.yaml (generated from template)
• Lando: Set php in .lando.yml recipe config (generated from template)

7. Adopt Mode Detection

When targeting an existing WordPress installation, check for wp-config.php at the project path to enter "adopt" mode:

# Check if wp-config.php exists at the target path
if [[ -f "/var/www/html/my-project/wp-config.php" ]]; then
    # Enter adopt mode — skip download, DB creation, and config creation
fi

Adopt Mode Behavior

When wp-config.php is found:

1. Skip: WordPress download, database creation, config creation, core install
2. Extract config from the existing install:

   $WP config list --format=json        # DB credentials, table prefix, debug settings
   $WP core version                      # WordPress version
   $WP plugin list --format=json         # Installed plugins
   $WP theme list --status=active --format=json  # Active theme
   $WP option get siteurl                # Current site URL
   $WP option get home                   # Current home URL
   $WP eval "echo PHP_VERSION;"          # PHP version in use
   

3. Populate the manifest from extracted values
4. Still execute: environment config generation (vhost/Docker), SSL, hosts entry, search-replace if domain changes
5. Edge cases:
   • Old WP version (< 5.0): Warn user, offer $WP core update
   • Multisite: Detect via $WP config get MULTISITE, abort with "Multisite not supported"

Summary Checklist

• Run bin/wp-env-setup.sh detect and parse the JSON output before making environment decisions
• Read .wp-create.json for all project configuration -- never hardcode values
• Use wp_cli.wrapper from the manifest as the WP-CLI command prefix
• Replace {{placeholders}} in .tpl files using manifest values
• Check for Docker port conflicts before starting containers
• Use OS-appropriate commands for PHP version management
• Detect wp-config.php to determine adopt mode vs fresh install
• All operations are idempotent -- safe to re-run