git:20261006.2c6b624 to git:20261006.3256c65

---

name: wp-environments

description: Local WordPress environment detection and setup — which engine a project runs on (native, Docker, DDEV, Lando, wp-env), the .wp-create.json manifest, WP-CLI wrapper selection, template placeholders, Docker port conflicts, PHP versions and adopt mode. Use when creating, adopting or configuring a local site, or when choosing how to run WP-CLI against one.

user-invocable: false

---

# 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

```bash

```

```json

```

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

```json

{

"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",

"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).

---

## 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.

| Environment | `wp_cli.wrapper` value |

|-------------|----------------------|

| Native | `wp --path=/var/www/html/my-project` |

| Docker | `docker exec my-project-wp wp --allow-root` |

| DDEV | `ddev wp` |

| Lando | `lando wp` |

| wp-env | `npx wp-env run cli wp` |

### Usage Pattern

```bash

# 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)

`wp-config.mjs get '${PROJECT_PATH}' db_password`, which resolves environment → local file →

manifest and warns when the last rung wins. Reading that field out of the manifest yields an

empty value on every project `/wp-create` has written since, and a silent legacy read on

---

## 5. Docker Port Conflict Detection

```bash

# macOS or fallback

```

---

## 6. PHP Version Management

### Native Environments

### Docker Environments

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

```yaml

# 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

Two different things share the word "adopt". `/wp-create`'s Adopt Mode, described here,

**reconfigures** an existing install into a `/wp-create` environment: vhost, SSL, hosts

entry, options. `/wp-adopt` (`bin/wp-config.mjs adopt`) only **registers** a site: it runs a

read-only probe and writes the manifest with `"origin": "adopted"`. Use it for a site that is

already served and only needs auditing, debugging or cloning into.

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

```bash

# 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:**

```bash

$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

- [ ] 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