Skip to content

Commit d6df50e

Browse files
fellyphakirk
fellyph
and
akirk
authored
A new README for the Playground CLI (#2284)
## Motivation for the change, related issues With the recent updates from the Playground CLI, this new README file contains some of the updates related to getting started with the CLI and the available commands. Due to the Blueprints V2, I haven't included as much information about setting up blueprints. Pull request related to issue #2224 --------- Co-authored-by: Alex Kirk <[email protected]>
1 parent 24a99c6 commit d6df50e

File tree

1 file changed

+160
-53
lines changed

1 file changed

+160
-53
lines changed

‎packages/playground/cli/README.md

Lines changed: 160 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,183 @@
11
# WordPress Playground CLI
22

3-
A CLI tool for running WordPress playground locally instead of in the browser:
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:
451

552
```shell
6-
$ bun packages/playground/cli/src/cli.ts server --wp=6.5
7-
WordPress is running on http://127.0.0.1:9400
53+
cd my-plugin-or-theme-directory
54+
npx @wp-playground/cli@latest server --mount=.:/wordpress/wp-content/plugins/
855
```
956

10-
Playground CLI is simple, configurable, and unopinionated. You can set it up
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.
1358

1459
```shell
15-
bun --config=/Users/adam/.bunfig.toml \
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
2461
```
2562

26-
It is long, sure, but it is also very flexible. If you need a shorter version, you can alias
27-
it or write a bash script. In the future, Blueprints might support relative path mappings,
28-
at which point that command would get much shorter.
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:
2976

30-
## Philosophy
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.
3180

32-
The data flow is as follows:
81+
The `server` command supports the following optional arguments:
3382

34-
- Start PHP
35-
- Mount any local directories
36-
- Put a fresh WordPress in the resulting virtual filesystem (unless you're mounting directly at /wordpress).
37-
- Run the Blueprint
38-
- Start a local server, accept requests
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.
3998

40-
On each run, a fresh WordPress release is unzipped in the virtual filesystem. It is sourced
41-
from a zip file cached at ~/.wordpress-playground/. If you mess up your site, just restart the
42-
server and you'll get a fresh one, again unzipped. The CLI tool never modifies the zip file
43-
so you can always be sure you're starting from a clean slate.
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+
```
44156

45-
## Future work
157+
## Comparisons
46158

47-
The CLI tool will have the following commands:
159+
### Things the Playground does compared to Laravel Valet
48160

49-
- `server` - start a fresh WordPress playground server.
50-
- `build-snapshot` - run a Blueprint and output a .zip file with the resulting WordPress instance.
51-
- `run-blueprint` - run a Blueprint and output errors to the console if they occur.
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.
52164

53-
It will also support:
165+
### Things the Playground does compared to `wp-env`
54166

55-
- Loading Blueprints from URLs.
56-
- Saving the running WordPress site and loading it later.
57-
- Caching all remote resources referenced in Blueprints. Currently, say, plugins are downloaded on each run.
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.
58170

59-
Conceptually, this isn't too different from Docker containers. There are images (zip files),
60-
containers (running instances), and commands (Blueprints). Playground could support the same
61-
concepts such as:
171+
## How can I contribute?
62172

63-
- Listing and managing available images and containers.
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.
69174

70-
## Interoperability
175+
Here are a few quick-start guides to get you started:
71176

72-
This CLI package is not just a useful tool. It drives interoperability between the in-browser
73-
Playground, CLI packages, and the PHP Blueprints library. Once complete, it will reuse the
74-
same internals as the website at https://playground.wordpress.org whether we're talking about
75-
running PHP code, executing Blueprints, building snapshots, serving requests, or maintaining
76-
multiple PHP instances
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

0 commit comments

Comments
 (0)