Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update wp-env prereq docs #50004

Merged
merged 2 commits into from
Apr 24, 2023
Merged

Update wp-env prereq docs #50004

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7f0c404
Update wp-env prereq docs
noahtallen Apr 21, 2023
94d648f
Add backticks around wp-env
noahtallen Apr 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 71 additions & 68 deletions packages/env/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,11 @@ The database credentials are: user `root`, password `password`. For a comprehens

## Prerequisites

`wp-env` requires Docker to be installed. There are instructions available for installing Docker on [Windows](https://docs.docker.com/desktop/install/windows-install/), [macOS](https://docs.docker.com/docker-for-mac/install/), and [Linux](https://docs.docker.com/desktop/install/linux-install/).
`wp-env` relies on a few commonly used developer tools:

Node.js and npm are required. The latest LTS version of Node.js is used to develop `wp-env` and is recommended.
- **Docker**. `wp-env` is powered by Docker. There are instructions available for installing Docker on [Windows](https://docs.docker.com/desktop/install/windows-install/) (we recommend the WSL2 backend), [macOS](https://docs.docker.com/docker-for-mac/install/), and [Linux](https://docs.docker.com/desktop/install/linux-install/).
- **Node.js**. `wp-env` is written as a Node script. We recommend using a Node version manager like [nvm](https://github.com/nvm-sh/nvm) to install the latest LTS version. Alternatively, you can [download it directly here](https://nodejs.org/en/download).
- **git**. Git is used for downloading software from source control, such as WordPress, plugins, and themes. [You can find the installation instructions here.](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)

## Installation

Expand Down Expand Up @@ -237,13 +239,13 @@ You should only have to translate `port` and `pathMappings` to the format used b

```json
{
"name": "Listen for XDebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html/wp-content/plugins/gutenberg": "${workspaceFolder}/"
}
"name": "Listen for XDebug",
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Everything below this must be from my autoformatter :P

"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html/wp-content/plugins/gutenberg": "${workspaceFolder}/"
}
}
```

Expand Down Expand Up @@ -329,6 +331,7 @@ wp-env run cli "wp --help"
Without the quotation marks, `wp-env` will print its own help text instead of
passing it to the container. If you experience any problems where the command
is not being passed correctly, fall back to using quotation marks.

</div>

```sh
Expand Down Expand Up @@ -468,44 +471,44 @@ You can customize the WordPress installation, plugins and themes that the develo
| `"plugins"` | `string[]` | `[]` | A list of plugins to install and activate in the environment. |
| `"themes"` | `string[]` | `[]` | A list of themes to install in the environment. |
| `"port"` | `integer` | `8888` (`8889` for the tests instance) | The primary port number to use for the installation. You'll access the instance through the port: 'http://localhost:8888'. |
| `"testsPort"` | `integer` | `8889` | The port number for the test site. You'll access the instance through the port: 'http://localhost:8889'. |
| `"testsPort"` | `integer` | `8889` | The port number for the test site. You'll access the instance through the port: 'http://localhost:8889'. |
| `"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. |

_Note: the port number environment variables (`WP_ENV_PORT` and `WP_ENV_TESTS_PORT`) take precedent over the .wp-env.json values._

Several types of strings can be passed into the `core`, `plugins`, `themes`, and `mappings` fields.

| Type | Format | Example(s) |
| ----------------- | -------------------------------------------- | -------------------------------------------------------- |
| Relative path | `.<path>\|~<path>` | `"./a/directory"`, `"../a/directory"`, `"~/a/directory"` |
| Absolute path | `/<path>\|<letter>:\<path>` | `"/a/directory"`, `"C:\\a\\directory"` |
| Type | Format | Example(s) |
| ----------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Relative path | `.<path>\|~<path>` | `"./a/directory"`, `"../a/directory"`, `"~/a/directory"` |
| Absolute path | `/<path>\|<letter>:\<path>` | `"/a/directory"`, `"C:\\a\\directory"` |
| GitHub repository | `<owner>/<repo>[#<ref>]` | `"WordPress/WordPress"`, `"WordPress/gutenberg#trunk"`, if no branch is provided wp-env will fall back to the repos default branch |
| SSH repository | `ssh://user@host/<owner>/<repo>.git[#<ref>]` | `"ssh://git@github.com/WordPress/WordPress.git"` |
| ZIP File | `http[s]://<host>/<path>.zip` | `"https://wordpress.org/wordpress-5.4-beta2.zip"` |
| SSH repository | `ssh://user@host/<owner>/<repo>.git[#<ref>]` | `"ssh://git@github.com/WordPress/WordPress.git"` |
| ZIP File | `http[s]://<host>/<path>.zip` | `"https://wordpress.org/wordpress-5.4-beta2.zip"` |

Remote sources will be downloaded into a temporary directory located in `~/.wp-env`.

Additionally, the key `env` is available to override any of the above options on an individual-environment basis. For example, take the following `.wp-env.json` file:

```json
{
"plugins": ["."],
"config": {
"KEY_1": true,
"KEY_2": false
},
"env": {
"development": {
"themes": ["./one-theme"]
},
"tests": {
"config": {
"KEY_1": false
},
"port": 3000
}
}
"plugins": [ "." ],
"config": {
"KEY_1": true,
"KEY_2": false
},
"env": {
"development": {
"themes": [ "./one-theme" ]
},
"tests": {
"config": {
"KEY_1": false
},
"port": 3000
}
}
}
```

Expand Down Expand Up @@ -548,8 +551,8 @@ This is useful for plugin development.

```json
{
"core": null,
"plugins": ["."]
"core": null,
"plugins": [ "." ]
}
```

Expand All @@ -559,8 +562,8 @@ This is useful for plugin development when upstream Core changes need to be test

```json
{
"core": "WordPress/WordPress#master",
"plugins": ["."]
"core": "WordPress/WordPress#master",
"plugins": [ "." ]
}
```

Expand All @@ -572,17 +575,17 @@ If you are running a _build_ of `wordpress-develop`, point `core` to the `build`

```json
{
"core": "../wordpress-develop/build",
"plugins": ["."]
"core": "../wordpress-develop/build",
"plugins": [ "." ]
}
```

If you are running `wordpress-develop` in a dev mode (e.g. the watch command `dev` or the dev build `build:dev`), then point `core` to the `src` directory.

```json
{
"core": "../wordpress-develop/src",
"plugins": ["."]
"core": "../wordpress-develop/src",
"plugins": [ "." ]
}
```

Expand All @@ -592,9 +595,9 @@ This is useful for integration testing: that is, testing how old versions of Wor

```json
{
"core": "WordPress/WordPress#5.2.0",
"plugins": ["WordPress/wp-lazy-loading", "WordPress/classic-editor"],
"themes": ["WordPress/theme-experiments"]
"core": "WordPress/WordPress#5.2.0",
"plugins": [ "WordPress/wp-lazy-loading", "WordPress/classic-editor" ],
"themes": [ "WordPress/theme-experiments" ]
}
```

Expand All @@ -604,12 +607,12 @@ You can add mu-plugins via the mapping config. The mapping config also allows yo

```json
{
"plugins": ["."],
"mappings": {
"wp-content/mu-plugins": "./path/to/local/mu-plugins",
"wp-content/themes": "./path/to/local/themes",
"wp-content/themes/specific-theme": "./path/to/local/theme-1"
}
"plugins": [ "." ],
"mappings": {
"wp-content/mu-plugins": "./path/to/local/mu-plugins",
"wp-content/themes": "./path/to/local/themes",
"wp-content/themes/specific-theme": "./path/to/local/theme-1"
}
}
```

Expand All @@ -619,10 +622,10 @@ Since all plugins in the `plugins` key are activated by default, you should use

```json
{
"plugins": ["."],
"mappings": {
"wp-content/plugins/my-test-plugin": "./path/to/test/plugin"
}
"plugins": [ "." ],
"mappings": {
"wp-content/plugins/my-test-plugin": "./path/to/test/plugin"
}
}
```

Expand All @@ -632,12 +635,12 @@ If you need a plugin active in one environment but not the other, you can use `e

```json
{
"plugins": ["."],
"env": {
"tests": {
"plugins": [".", "path/to/test/plugin"]
}
}
"plugins": [ "." ],
"env": {
"tests": {
"plugins": [ ".", "path/to/test/plugin" ]
}
}
}
```

Expand All @@ -647,13 +650,13 @@ You can tell `wp-env` to use a custom port number so that your instance does not

```json
{
"plugins": ["."],
"port": 4013,
"env": {
"tests": {
"port": 4012
}
}
"plugins": [ "." ],
"port": 4013,
"env": {
"tests": {
"port": 4012
}
}
}
```

Expand All @@ -663,8 +666,8 @@ You can tell `wp-env` to use a specific PHP version for compatibility and testin

```json
{
"phpVersion": "7.2",
"plugins": ["."]
"phpVersion": "7.2",
"plugins": [ "." ]
}
```

Expand Down