@wp-playground/cli 1.1.5 → 1.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +160 -53
- package/cli.cjs +1 -1
- package/cli.js +1 -1
- package/index.cjs +1 -1
- package/index.js +1 -1
- package/package.json +11 -11
- package/{run-cli-bX1Rsm_j.js → run-cli-CbJy_CRO.js} +928 -924
- package/{run-cli-bX1Rsm_j.js.map → run-cli-CbJy_CRO.js.map} +1 -1
- package/{run-cli-DXlWqHJ-.cjs → run-cli-Dff9jZvG.cjs} +11 -11
- package/{run-cli-DXlWqHJ-.cjs.map → run-cli-Dff9jZvG.cjs.map} +1 -1
package/README.md
CHANGED
|
@@ -1,76 +1,183 @@
|
|
|
1
1
|
# WordPress Playground CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
`@wp-playground/cli` streamlines the process of setting up a local WordPress environment for development and testing. It utilizes WordPress Playground to set up a new WordPress environment seamlessly. As with its predecessor `wp-now`, you can switch between PHP and WordPress versions only with a flag.
|
|
4
|
+
|
|
5
|
+
# Table of contents
|
|
6
|
+
|
|
7
|
+
- [Requirements](#requirements)
|
|
8
|
+
- [Quickstart](#quickstart)
|
|
9
|
+
- [Usage](#usage)
|
|
10
|
+
- [Working with Blueprints](#working-with-blueprints)
|
|
11
|
+
- [How can I contribute?](#how-can-i-contribute)
|
|
12
|
+
|
|
13
|
+
## Requirements
|
|
14
|
+
|
|
15
|
+
The Playground CLI requires Node.js 20.18 or higher, which is the recommended Long-Term Support (LTS) version. You can download it from the [Node.js website](https://nodejs.org/en/download).
|
|
16
|
+
|
|
17
|
+
## Quickstart
|
|
18
|
+
|
|
19
|
+
Running the Playground CLI is as simple as going to your plugin or theme directory and running the following command:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
cd my-plugin-or-theme-directory
|
|
23
|
+
npx @wp-playground/cli server --auto-mount
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
The flag `--auto-mount` will figure out if the project folder is a plugin or a theme for you. For more advanced mounting options, see the [Mounting Local Directories](#mounting-local-directories) section.
|
|
27
|
+
|
|
28
|
+
## Usage
|
|
29
|
+
|
|
30
|
+
You don't have to install `@wp-playground/cli`, you can run it directly with `npx`. This is the recommended way to use the CLI and requires no permanent installation. To run a vanilla WordPress website, you can run the command:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
npx @wp-playground/cli@latest server
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
> **_NOTE:_** You can also use the `@wp-playground/cli@latest` to load the latest version of playground.
|
|
37
|
+
|
|
38
|
+
### Choosing a WordPress Version
|
|
39
|
+
|
|
40
|
+
By default, the CLI loads the latest stable version of WordPress and PHP 8.0 due to its improved performance. To specify your preferred versions, you can use the flag `--wp=<version>` and `--php=<version>`:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
npx @wp-playground/cli@latest server --wp=6.8 --php=8.4
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### Mounting local Directories
|
|
47
|
+
|
|
48
|
+
`@wp-playground/cli` operates by mounting your local project files into a virtualized WordPress environment. This allows you to work on your plugin or theme with a live WordPress instance without any complex setup. You can do this automatically or manually.
|
|
49
|
+
|
|
50
|
+
For full control, you can manually mount a local directory to a specific path inside the virtual WordPress installation. For example, to mount your current project folder into the plugins directory, use the `--mount` flag:
|
|
4
51
|
|
|
5
52
|
```shell
|
|
6
|
-
|
|
7
|
-
|
|
53
|
+
cd my-plugin-or-theme-directory
|
|
54
|
+
npx @wp-playground/cli@latest server --mount=.:/wordpress/wp-content/plugins/
|
|
8
55
|
```
|
|
9
56
|
|
|
10
|
-
|
|
11
|
-
to your unique WordPress setup. For example, this command would run the documentation
|
|
12
|
-
workflow at https://github.com/adamziel/playground-docs-workflow:
|
|
57
|
+
Another helpful flag is `--mount-before-install` allows the users to create a site in a local filesystem instead of in the Virtual File System.
|
|
13
58
|
|
|
14
59
|
```shell
|
|
15
|
-
|
|
16
|
-
./packages/playground/cli/src/cli.ts \
|
|
17
|
-
server \
|
|
18
|
-
--mount=./wp-content/plugins/wp-docs-plugin:/wordpress/wp-content/plugins/wp-docs-plugin \
|
|
19
|
-
--mount=./wp-content/html-pages:/wordpress/wp-content/html-pages \
|
|
20
|
-
--mount=./wp-content/uploads:/wordpress/wp-content/uploads \
|
|
21
|
-
--mount=./wp-content/themes/playground-docs:/wordpress/wp-content/themes/playground-docs \
|
|
22
|
-
--blueprint=./wp-content/blueprint-wp-now.json \
|
|
23
|
-
--wp=6.5
|
|
60
|
+
npx @wp-playground/cli@latest server --mount-before-install=./my-local-site:/wordpress
|
|
24
61
|
```
|
|
25
62
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
63
|
+
### Automatic Mounting with `--auto-mount`
|
|
64
|
+
|
|
65
|
+
The `--auto-mount` flag is the easiest way to get started. It inspects the current directory and automatically mounts it to the correct location in the virtual WordPress site. These are the supported directory types and how they are detected:
|
|
66
|
+
|
|
67
|
+
- **Plugin Mode**: Presence of a PHP file with `Plugin Name:` in its header.
|
|
68
|
+
- **Theme Mode**: Presence of a style.css file with `Theme Name:` in its header.
|
|
69
|
+
- **wp-content Mode**: Presence of plugins and themes subdirectories.
|
|
70
|
+
- **WordPress Mode**: Presence of a complete WordPress installation. The directory will be mounted to the root `/wordpress` folder.
|
|
71
|
+
|
|
72
|
+
## Command and Arguments
|
|
73
|
+
|
|
74
|
+
Playground CLI is simple, configurable, and unopinionated. You can set it up according
|
|
75
|
+
to your unique WordPress setup. With the Playground CLI, you can use the following top-level commands:
|
|
29
76
|
|
|
30
|
-
|
|
77
|
+
- **`server`**: (Default) Starts a local WordPress server.
|
|
78
|
+
- **`run-blueprint`**: Executes a Blueprint file without starting a web server.
|
|
79
|
+
- **`build-snapshot`**: Builds a ZIP snapshot of a WordPress site based on a Blueprint.
|
|
31
80
|
|
|
32
|
-
The
|
|
81
|
+
The `server` command supports the following optional arguments:
|
|
33
82
|
|
|
34
|
-
-
|
|
35
|
-
-
|
|
36
|
-
-
|
|
37
|
-
-
|
|
38
|
-
-
|
|
83
|
+
- `--port=<port>`: The port number for the server to listen on. Defaults to 9400.
|
|
84
|
+
- `--outfile`: When building, write to this output file.
|
|
85
|
+
- `--wp=<version>`: The version of WordPress to use. Defaults to the latest.
|
|
86
|
+
- `--auto-mount`: Automatically mount the current directory (plugin, theme, wp-content, etc.).
|
|
87
|
+
- `--mount=<mapping>`: Manually mount a directory (can be used multiple times). Format: /host/path:/vfs/path
|
|
88
|
+
- `--mount-before-install`: Mount a directory to the PHP runtime before WordPress installation (can be used multiple times). Format: `"/host/path:/vfs/path"`.
|
|
89
|
+
- `--mount-dir`: Mount a directory to the PHP runtime (can be used multiple times). Format: `"/host/path"` `"/vfs/path"`.
|
|
90
|
+
- `--mount-dir-before-install`: Mount a directory before WordPress installation (can be used multiple times). Format: `"/host/path"` `"/vfs/path"`
|
|
91
|
+
- `--blueprint=<path>`: The path to a JSON Blueprint file to execute.
|
|
92
|
+
- `--blueprint-may-read-adjacent-files`: Consent flag: Allow "bundled" resources in a local blueprint to read files in the same directory as the blueprint file.
|
|
93
|
+
- `--login`: Automatically log the user in as an administrator.
|
|
94
|
+
- `--skip-wordpress-setup`: Do not download or install WordPress. Useful if you are mounting a full WordPress directory.
|
|
95
|
+
- `--skip-sqlite-setup`: Do not set up the SQLite database integration.
|
|
96
|
+
- `--quiet`: Do not output logs and progress messages.
|
|
97
|
+
- `--debug`: Print the PHP error log if an error occurs during boot.
|
|
39
98
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
99
|
+
## Need some help with the CLI?
|
|
100
|
+
|
|
101
|
+
With the Playground CLI, you can use the `--help` to get some support about the available commands.
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
npx @wp-playground/cli@latest --help
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## Working with Blueprints
|
|
108
|
+
|
|
109
|
+
Blueprint is a JSON file where you can pre-define the initial state of your WordPress instance. It provides several functionalities, like installing plugins and themes, creating content, setting WordPress options, and executing steps.
|
|
110
|
+
|
|
111
|
+
```JSON
|
|
112
|
+
{
|
|
113
|
+
"$schema": "https://playground.wordpress.net/blueprint-schema.json",
|
|
114
|
+
"landingPage": "/wp-admin/post-new.php",
|
|
115
|
+
"steps": [
|
|
116
|
+
{
|
|
117
|
+
"step": "installPlugin",
|
|
118
|
+
"pluginZipFile": {
|
|
119
|
+
"resource": "wordpress.org/plugins",
|
|
120
|
+
"slug": "gutenberg"
|
|
121
|
+
},
|
|
122
|
+
"options": {
|
|
123
|
+
"activate": true
|
|
124
|
+
}
|
|
125
|
+
},
|
|
126
|
+
{
|
|
127
|
+
"step": "login",
|
|
128
|
+
"username": "admin",
|
|
129
|
+
"password": "password"
|
|
130
|
+
}
|
|
131
|
+
]
|
|
132
|
+
}
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
The example of a Blueprint above installs a plugin, logs the user in, and opens the new post editor. To learn more about Blueprints, please check the [documentation](https://wordpress.github.io/wordpress-playground/blueprints).
|
|
136
|
+
|
|
137
|
+
To use a Blueprint, create a file (e.g., my-blueprint.json) and run the following command:
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
npx @wp-playground/cli@latest server --blueprint=./my-blueprint.json
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
## Programmatic Usage with JavaScript
|
|
144
|
+
|
|
145
|
+
The Playground CLI can be controlled programmatically from your JavaScript code using the `runCLI` function. This allows you to integrate all CLI functionalities directly into your development workflow, for example, end-to-end testing.
|
|
146
|
+
|
|
147
|
+
```JavaScript
|
|
148
|
+
import { runCLI } from "@wp-playground/cli";
|
|
149
|
+
|
|
150
|
+
const cliServer = await runCLI({
|
|
151
|
+
command: "server"
|
|
152
|
+
});
|
|
153
|
+
const handler = cliServer.requestHandler;
|
|
154
|
+
const php = await handler.getPrimaryPhp();
|
|
155
|
+
```
|
|
44
156
|
|
|
45
|
-
##
|
|
157
|
+
## Comparisons
|
|
46
158
|
|
|
47
|
-
|
|
159
|
+
### Things the Playground does compared to Laravel Valet
|
|
48
160
|
|
|
49
|
-
-
|
|
50
|
-
-
|
|
51
|
-
-
|
|
161
|
+
- Handles the entire WordPress installation for you.
|
|
162
|
+
- Works across all desktop platforms (Mac, Linux, Windows).
|
|
163
|
+
- Does not set up custom host domains for you.
|
|
52
164
|
|
|
53
|
-
|
|
165
|
+
### Things the Playground does compared to `wp-env`
|
|
54
166
|
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
167
|
+
- Does not require Docker.
|
|
168
|
+
- Is faster to start up for quick tests and development.
|
|
169
|
+
- The Playground doesn't come with a MySQL Server, but you can provide your own MySQL credentials.
|
|
58
170
|
|
|
59
|
-
|
|
60
|
-
containers (running instances), and commands (Blueprints). Playground could support the same
|
|
61
|
-
concepts such as:
|
|
171
|
+
## How can I contribute?
|
|
62
172
|
|
|
63
|
-
-
|
|
64
|
-
- Saving a running container and restoring it later
|
|
65
|
-
- Starting a container from a specific image (already supported via zip files)
|
|
66
|
-
- Running a command in a container (the `php` command)
|
|
67
|
-
- Building a new image from a Blueprint (the `build` command)
|
|
68
|
-
- Step-by-step cache for Blueprints so that only the changed steps are re-run.
|
|
173
|
+
WordPress Playground CLI is an open-source project and welcomes all contributors from documentation to triage. If the feature you need is missing, you are more than welcome to start a discussion, open an issue, and even propose a Pull Request to implement it.
|
|
69
174
|
|
|
70
|
-
|
|
175
|
+
Here are a few quick-start guides to get you started:
|
|
71
176
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
177
|
+
- Code contributions – see the [developer section](https://wordpress.github.io/wordpress-playground/docs/contributing/code).
|
|
178
|
+
- Documentation – see the [documentation section](https://wordpress.github.io/wordpress-playground/docs/contributing/documentation).
|
|
179
|
+
- Triage – see the [triage section](https://wordpress.github.io/wordpress-playground/contributing/#triaging-issues).
|
|
180
|
+
- Contributions to translations – see the [translations section](https://wordpress.github.io/wordpress-playground/contributing/translations).
|
|
181
|
+
- Reporting bugs – open an [issue](https://github.com/WordPress/wordpress-playground/issues/new) in the repository.
|
|
182
|
+
- Ideas, designs, or anything else – open a [GitHub discussion](https://github.com/WordPress/wordpress-playground/discussions) and let's talk!
|
|
183
|
+
- Join our Slack channel [#playground](https://wordpress.slack.com/archives/C04EWKGDJ0K) at Make WordPress
|
package/cli.cjs
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
"use strict";const s=require("./run-cli-
|
|
1
|
+
"use strict";const s=require("./run-cli-Dff9jZvG.cjs");s.parseOptionsAndRunCLI().catch(()=>{process.exit(1)});
|
|
2
2
|
//# sourceMappingURL=cli.cjs.map
|
package/cli.js
CHANGED
package/index.cjs
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("./run-cli-
|
|
1
|
+
"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("./run-cli-Dff9jZvG.cjs");exports.parseOptionsAndRunCLI=n.parseOptionsAndRunCLI;exports.runCLI=n.runCLI;
|
|
2
2
|
//# sourceMappingURL=index.cjs.map
|
package/index.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wp-playground/cli",
|
|
3
|
-
"version": "1.1
|
|
3
|
+
"version": "1.2.1",
|
|
4
4
|
"description": "WordPress Playground CLI",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
"module": "./index.js",
|
|
33
33
|
"types": "index.d.ts",
|
|
34
34
|
"bin": "wp-playground.js",
|
|
35
|
-
"gitHead": "
|
|
35
|
+
"gitHead": "704706298eeb080e63bb652cd02ea1647e4ba657",
|
|
36
36
|
"dependencies": {
|
|
37
37
|
"@zip.js/zip.js": "2.7.57",
|
|
38
38
|
"ajv": "8.12.0",
|
|
@@ -56,15 +56,15 @@
|
|
|
56
56
|
"wasm-feature-detect": "1.8.0",
|
|
57
57
|
"ws": "8.18.1",
|
|
58
58
|
"yargs": "17.7.2",
|
|
59
|
-
"@wp-playground/blueprints": "1.1
|
|
60
|
-
"@php-wasm/progress": "1.1
|
|
61
|
-
"@php-wasm/universal": "1.1
|
|
62
|
-
"@php-wasm/node": "1.1
|
|
63
|
-
"@php-wasm/logger": "1.1
|
|
64
|
-
"@wp-playground/storage": "1.1
|
|
65
|
-
"@wp-playground/common": "1.1
|
|
66
|
-
"@wp-playground/wordpress": "1.1
|
|
67
|
-
"@php-wasm/util": "1.1
|
|
59
|
+
"@wp-playground/blueprints": "1.2.1",
|
|
60
|
+
"@php-wasm/progress": "1.2.1",
|
|
61
|
+
"@php-wasm/universal": "1.2.1",
|
|
62
|
+
"@php-wasm/node": "1.2.1",
|
|
63
|
+
"@php-wasm/logger": "1.2.1",
|
|
64
|
+
"@wp-playground/storage": "1.2.1",
|
|
65
|
+
"@wp-playground/common": "1.2.1",
|
|
66
|
+
"@wp-playground/wordpress": "1.2.1",
|
|
67
|
+
"@php-wasm/util": "1.2.1"
|
|
68
68
|
},
|
|
69
69
|
"overrides": {
|
|
70
70
|
"rollup": "^4.34.6",
|