From d9922c16576555e7c99c259d2afa1891833e8771 Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Wed, 1 May 2024 17:10:26 +0200 Subject: [PATCH 1/6] Update wp-now documentation --- packages/wp-now/README.md | 325 ++++++++++++++++++++------------------ 1 file changed, 175 insertions(+), 150 deletions(-) diff --git a/packages/wp-now/README.md b/packages/wp-now/README.md index c3f51e4d..98fe22f6 100644 --- a/packages/wp-now/README.md +++ b/packages/wp-now/README.md @@ -2,28 +2,28 @@ `wp-now` streamlines the process of setting up a local WordPress environment. -It uses automatic mode detection to provide a fast setup process, regardless of whether you're working on a plugin or an entire site. You can easily switch between PHP and WordPress versions with just a configuration argument. Under the hood, `wp-now` is powered by WordPress Playground and only requires Node.js. +It uses automatic mode detection to provide a fast setup process, regardless of whether you're working on a plugin or an entire site. You can easily switch between PHP and WordPress versions with a configuration flag. Under the hood, `wp-now` is powered by WordPress Playground and only requires Node.js. ![Demo GIF of wp-now](https://github.com/WordPress/playground-tools/assets/779993/d75cb2fe-c75a-489b-9db5-29258ff7e27f) ## Quickstart -### Launching wp-now in a Plugin or Theme Directory +### Launch wp-now in a plugin or theme directory -Running wp-now is as simple as accessing your plugin or theme directory and starting wp-now. +Running `wp-now` is as simple as accessing your plugin or theme directory and running the following command: ```bash cd my-plugin-or-theme-directory npx @wp-now/wp-now start ``` -### Launching wp-now in the wp-content Directory with Options +### Launch wp-now in the `wp-content` directory with options -You can also start wp-now from any wp-content folder. In this example, we pass parameters to change the PHP and WordPress versions and apply a blueprint file. +You can also start `wp-now` from any `wp-content` folder. In this example, you pass parameters to change the PHP and WordPress versions and apply a Blueprint file. ```bash cd my-wordpress-folder/wp-content -npx @wp-now/wp-now start --wp=5.9 --php=7.4 --blueprint=path/to/blueprint-example.json +npx @wp-now/wp-now start --wp=6.4 --php=8.0 --blueprint=path/to/blueprint-example.json ``` ## Table of Contents @@ -31,13 +31,13 @@ npx @wp-now/wp-now start --wp=5.9 --php=7.4 --blueprint=path/to/blueprint-examp - [Quickstart](#quickstart) - [Requirements](#requirements) - [Usage](#usage) - - [Automatic Modes](#automatic-modes) + - [Automatic modes](#automatic-modes) - [Arguments](#arguments) -- [Technical Details](#technical-details) +- [Technical details](#technical-details) - [Using Blueprints](#using-blueprints) - - [Defining Custom URLs](#defining-custom-urls) - - [Defining Debugging Constants](#defining-debugging-constants) -- [Known Issues](#known-issues) + - [Define custom URLs in a Blueprint](#defining-custom-urls) + - [Define debugging constants in a Blueprint](#defining-debugging-constants) +- [Known issues](#known-issues) - [Comparisons](#comparisons) - [Laravel Valet](#laravel-valet) - [wp-env](#wp-env) @@ -47,27 +47,27 @@ npx @wp-now/wp-now start --wp=5.9 --php=7.4 --blueprint=path/to/blueprint-examp ## Requirements -Node 18 is the minimum supported version. Node 20 is required for Blueprint support. +The minimum supported version of Node.js is 18. For Blueprint support, install Node 20. ## Usage -To run `wp-now` with one command, you can use [npx](https://docs.npmjs.com/cli/v10/commands/npx). This is our recommended way to use `wp-now` as it doesn't require any installation or setup.: +You don't have to install `wp-now`—you can run it with a single [npx](https://docs.npmjs.com/cli/v10/commands/npx) command. That's the recommended way to use `wp-now` and requires no installation or setup: ```bash npx @wp-now/wp-now start ``` -You can also install `@wp-now/wp-now` globally to just run `wp-now` from any directory: +You can also install `@wp-now/wp-now` globally to run it from any directory: ```bash npm install -g @wp-now/wp-now ``` -Lastly, you can install `wp-now` via `git clone` if you'd like to hack on it too. See [Contributing](#contributing) for more details. +Lastly, you can install `wp-now` via `git clone`. See [Contributing](#contributing) for more details. -Once installed, you can start a new server like so: +Once installed, start a new server like so: ```bash cd wordpress-plugin-or-theme @@ -80,7 +80,9 @@ Use the `--php=` and `--wp=` arguments to switch to different wp-now start --wp=5.9 --php=7.4 ``` -For the modes that support it, `wp-now` will create a persistent SQLite database and `wp-content` directory in `~/.wp-now`. Use the `--reset` argument to create a fresh project. +In supported modes, `wp-now` creates a persistent SQLite database and `wp-content` directory in `~/.wp-now`. + +Use the `--reset` argument to create a new project. Use `wp-now php ` to execute a specific PHP file: @@ -89,211 +91,234 @@ cd wordpress-plugin-or-theme wp-now php my-file.php ``` -### Automatic Modes +### Automatic modes + +`wp-now` operates in a few different modes for both the `start` and the `php` commands. The selected mode depends on the directory in which you execute the command: -`wp-now` automatically operates in a few different modes for both the `start` and the `php` commands. The selected mode depends on the directory in which it is executed: +- **plugin**, **theme**, or **wp-content**: Loads the project files into a virtual filesystem with WordPress and a SQLite-based database. Everything (including WordPress core files, the database, `wp-config.php`, etc.) is stored in the user's home directory and loaded into the virtual file system (VFS). `wp-now` uses the latest WordPress version unless you define the `--wp=` argument. -- **plugin**, **theme**, or **wp-content**: Loads the project files into a virtual filesytem with WordPress and a SQLite-based database. Everything (including WordPress core files, the database, `wp-config.php`, etc.) is stored in the user's home directory and loaded into the virtual filesystem. The latest version of WordPress will be used, unless the `--wp=` argument is provided. Here are the heuristics for each mode: - - **plugin** mode: Presence of a PHP file with 'Plugin Name:' in its contents. - - **theme** mode: Presence of a `style.css` file with 'Theme Name:' in its contents. +Here are the heuristics for each mode: + - **plugin** mode: Presence of a PHP file with "Plugin Name:" in its contents. + - **theme** mode: Presence of a `style.css` file with "Theme Name:" in its contents. - **wp-content** mode: Presence of `plugins` and `themes` subdirectories. -- **wordpress**: Runs the directory as a WordPress installation when WordPress files are detected. An existing `wp-config.php` file will be used if it exists; if it doesn't exist, it will be created along with a SQLite database. -- **wordpress-develop**: Same as `wordpress` mode, except the `build` directory is served as the web root. -- **index**: When an `index.php` file is present, starts a PHP webserver in the working directory and simply passes requests to the `index.php`. -- **playground**: If no other conditions are matched, launches a completely virtualized WordPress site. +- **wordpress**: Runs the directory as a WordPress installation when WordPress files are detected. If it exists, `wp-now` will use the `wp-config.php` file or create one with a SQLite database. +- **wordpress-develop**: Same as `wordpress` mode, except the `build` directory is the web root. +- **index**: When an `index.php` file is present, `wp-now` starts a PHP web server in the working directory and passes requests to the file. +- **playground**: If no other conditions are matched, `wp-now` launches a virtualized WordPress site. ### Arguments -`wp-now start` currently supports the following arguments: +You can run `wp-now` with the `--help` flag to get an overview of all the available options. + +```bash +wp-now --help -- `--path=`: the path to the PHP file or WordPress project to use. If not provided, it will use the current working directory; -- `--php=`: the version of PHP to use. This is optional and if not provided, it will use a default version which is `8.0`(example usage: `--php=7.4`); -- `--port=`: the port number on which the server will listen. This is optional and if not provided, it will pick an open port number automatically. The default port number is set to `8881`(example of usage: `--port=3000`); -- `--wp=`: the version of WordPress to use. This is optional and if not provided, it will use a default version. The default version is set to the [latest WordPress version](https://wordpress.org/download/releases/)(example usage: `--wp=5.8`) -- `--blueprint=`: the path of a JSON file with the Blueprint steps (requires Node 20). This is optional, if provided will execute the defined Blueprints. See [Using Blueprints](#using-blueprints) for more details. -- `--reset`: create a fresh SQLite database and wp-content directory, for modes that support persistence. +# or +wp-now start --help -Of these, `wp-now php` currently supports the `--path=` and `--php=` arguments. +# or +wp-now php --help +``` -## Technical Details +`wp-now start` supports the following optional arguments: -- The `~/.wp-now` home directory is used to store the WP versions and the `wp-content` folders for projects using 'theme', 'plugin', 'wp-content', and 'playground' modes. The path to `wp-content` directory for the 'plugin', 'theme', and 'wp-content' modes is `~/.wp-now/wp-content/${projectName}-${directoryHash}`. 'playground' mode shares the same `~/.wp-now/wp-content/playground` directory, regardless of where it's started. -- For the database setup, `wp-now` is using [SQLite database integration plugin](https://wordpress.org/plugins/sqlite-database-integration/). The path to SQLite database is ` ~/.wp-now/wp-content/${projectName}-${directoryHash}/database/.ht.sqlite` +- `--path=`: The path to the PHP file or WordPress project to use. If not provided, it will use the current working directory. +- `--php=`: The version of PHP to use. The default version is `8.0`. +- `--port=`: The port number on which the server will listen. The default port number is `8881`. If it's in use, `wp-now` picks an open port number. +- `--wp=`: The version of WordPress to use. The default is the [latest WordPress version](https://wordpress.org/download/releases/). +- `--blueprint=`: The path to a JSON file with the Blueprint steps (requires Node 20). If provided, `wp-now` executes the steps. See [Using Blueprints](#using-blueprints) for more details. +- `--reset`: Creates a fresh SQLite database and `wp-content` directory for modes that support persistence. -## Using Blueprints +`wp-now php` supports the `--path=` and `--php=` arguments. -Blueprints are JSON files with a list of steps to execute after starting wp-now. They can be used to automate the setup of a WordPress site, including defining wp-config constants, installing plugins, themes, and content. [Learn more about Blueprints.](https://wordpress.github.io/wordpress-playground/blueprints-api/index) +## Technical details -### Defining Custom URLs +`wp-now` stores all relevant files in a hidden directory within your user home directory: `~/.wp-now`. -Here is an example of a Blueprint that defines custom URL constant. `wp-now` will automatically detect the blueprint and execute it after starting the server. In consequence, the site will be available at `http://myurl.wpnow`. Make sure myurl.wpnow is added to your hosts file. +- When running in **plugin**, **theme**, **wp-content**, and **playground** modes, the WordPress core files and `wp-content` will be available in `~/.wp-now/wp-content/${projectName}-${directoryHash}`. 'playground' mode shares the same `~/.wp-now/wp-content/playground` directory, regardless of where it runs. +- For the database setup, `wp-now` uses [SQLite database integration plugin](https://wordpress.org/plugins/sqlite-database-integration/). The path to the database is ` ~/.wp-now/wp-content/${projectName}-${directoryHash}/database/.ht.sqlite` -To execute this Blueprint, create a file named `blueprint-example.json` and run `wp-now start --blueprint=path/to/blueprint-example.json`. Note that the `method` is set to `define-before-run` to avoid modifying the `wp-config.php` file that is shared between all the projects. In contrast, the method `rewrite-wp-config` will modify the `wp-config.php` in disk. +## Using Blueprints + +Blueprints are JSON files that define a list of steps to execute after starting `wp-now`. Blueprints automate the setup of a WordPress site, including defining wp-config constants, installing plugins and themes, and creating content. + +Below is an example of a Blueprint that runs the latest versions of WordPress and PHP, installs [bundled PHP extensions](https://wordpress.github.io/wordpress-playground/blueprints-api/data-format#php-extensions), logs the user in as an Administrator, and opens a new post window. ```json { - "steps": [ - { - "step": "defineWpConfigConsts", - "consts": { - "WP_HOME": "http://myurl.wpnow:8881", - "WP_SITEURL": "http://myurl.wpnow:8881" - }, - "method": "define-before-run" - } - ] + "$schema": "https://playground.wordpress.net/blueprint-schema.json", + "landingPage": "/wp-admin/post-new.php", + "preferredVersions": { + "php": "latest", + "wp": "latest" + }, + "phpExtensionBundles": ["kitchen-sink"], + "steps": [ + { + "step": "login", + "username": "admin", + "password": "password" + } + ] } ``` -This step can be also used along with `ngrok`, in this case you can run `ngrok http 8881`, copy the ngrok URL and replace `WP_HOME` and `WP_SITEURL` in the blueprint file. +You can prototype and test your Blueprint in a [dedicated online editor](https://playground.wordpress.net/builder/builder.html). -If you prefer to use a different port, you can use the `--port` argument when starting the server. -`wp-now start --blueprint=path/to/blueprint-example.json --port=80` +To run it, create a file named `blueprint-example.json` and run the following command: + +```bash +wp-now start --blueprint=path/to/blueprint-example.json +``` -The Blueprint to listen on port `80` will look like this: +### Define custom URLs in a Blueprint + +As the building blocks of Playground, Blueprints offer advanced functionality, and we recommend you [learn more about how to use them](https://wordpress.github.io/wordpress-playground/blueprints-api/index) before you get started. + +Here's an example of a Blueprint that defines a custom URL constant in `wp-config.php` using [`WP_HOME`](https://developer.wordpress.org/advanced-administration/wordpress/wp-config/#blog-address-url) and [`WP_SITEURL`](https://developer.wordpress.org/advanced-administration/wordpress/wp-config/#wp-siteurl). + +Assuming you added `myurl.wpnow` to your `hosts` file, your site will be available at `http://myurl.wpnow`. + +Note that the `method` is set to `define-before-run` to avoid modifying the shared `wp-config.php` file. The default method, `rewrite-wp-config`, _modifies_ the `wp-config.php` on the disk. ```json { - "steps": [ - { - "step": "defineWpConfigConsts", - "consts": { - "WP_HOME": "http://myurl.wpnow", - "WP_SITEURL": "http://myurl.wpnow" - }, - "method": "define-before-run" - } - ] + "steps": [ + { + "step": "defineWpConfigConsts", + "consts": { + "WP_HOME": "http://myurl.wpnow:8881", + "WP_SITEURL": "http://myurl.wpnow:8881" + }, + "method": "define-before-run" + } + ] } ``` -### Defining Debugging Constants +You can use this instance with [`ngrok`](https://ngrok.com/docs): +1. Run `ngrok http 8881` +2. Copy the URL, and +3. Replace `WP_HOME` and `WP_SITEURL` in the Blueprint file. -In the similar way we can define `WP_DEBUG` constants and read the debug logs. +You can also define a different port: -Run `wp-now start --blueprint=path/to/blueprint-example.json` where `blueprint-example.json` is: +```bash +wp-now start --blueprint=path/to/blueprint-example.json --port=80 +``` + +The Blueprint to listen on port `80` would look like this: ```json { - "steps": [ - { - "step": "defineWpConfigConsts", - "consts": { - "WP_DEBUG": true - } - } - ] + "steps": [ + { + "step": "defineWpConfigConsts", + "consts": { + "WP_HOME": "http://myurl.wpnow", + "WP_SITEURL": "http://myurl.wpnow" + }, + "method": "define-before-run" + } + ] } ``` -Because we didn't define a method for `defineWpConfigConsts`, and the default method is `rewrite-wp-config`, this blueprint will update your `~/.wp-now/wordpress-versions/latest/wp-config.php` enabling the WP_DEBUG constant and will create a `debug.log` file in the `~/.wp-now/wp-content/${project}/debug.log` directory. -The next time you execute `wp-now start` in any project, the variable `WP_DEBUG` will still be set to true. +### Define debugging constants in a Blueprint -If you prefer to set a custom path for the debug log file, you can set `WP_DEBUG_LOG` to be a directory. Remember that the `php-wasm` server runs under a VFS (virtual file system) where the default documentRoot for wp-now is always `/var/www/html`. +Similarly, you can define [`WP_DEBUG`](https://developer.wordpress.org/advanced-administration/debug/debug-wordpress/) constants and inspect the debug logs. -For example, if you run `wp-now start --blueprint=path/to/blueprint-example.json` from a theme named `atlas` you could use this directory: `/var/www/html/wp-content/themes/atlas/example.log` and you will find the `example.log` file in your project directory. +Here's the example Blueprint: ```json { - "steps": [ - { - "step": "defineWpConfigConsts", - "consts": { - "WP_DEBUG": true, - "WP_DEBUG_LOG": "/var/www/html/wp-content/themes/atlas/example.log" - }, - "method": "define-before-run" - } - ] + "steps": [ + { + "step": "defineWpConfigConsts", + "consts": { + "WP_DEBUG": true + } + } + ] } ``` -## Known Issues +Because you didn't define a method for `defineWpConfigConsts`, the Blueprint uses the default `rewrite-wp-config` and updates the file stored in `~/.wp-now/wordpress-versions/latest/wp-config.php`. +The next time you execute `wp-now start` in any project, the variable `WP_DEBUG` will be set to true. -- Running `wp-now start` in 'wp-content' or 'wordpress' mode will produce some empty directories: [WordPress/wordpress-playground#328](https://github.com/WordPress/wordpress-playground/issues/328) -- Inline images are broken when site starts on a different port: [WordPress/wordpress-playground#356](https://github.com/WordPress/wordpress-playground/issues/356) -- `wp-now` doesn't build or start on Windows: [WordPress/playground-tools#66](https://github.com/WordPress/playground-tools/issues/66), [WordPress/playground-tools#11](https://github.com/WordPress/playground-tools/issues/11) -- It's not possible to set `WP_DEBUG` and other `wp-config.php` constants: [WordPress/playground-tools#17](https://github.com/WordPress/playground-tools/issues/17) -- In 'wordpress' mode, `wp-now` can connect to a MySQL database with `define( 'DB_HOST', '127.0.0.1' );`, but `define( 'DB_HOST', 'localhost' );` does not work: [WordPress/wordpress-playground#369](https://github.com/WordPress/wordpress-playground/issues/369) -- `wp-now` published versions can appear random: [WordPress/wordpress-playground#357](https://github.com/WordPress/wordpress-playground/issues/357) +If you open `wp-config.php`, you'll see the following lines: -## Comparisons +```php +define( 'WP_DEBUG', true ); +define( 'WP_DEBUG_LOG', true ); +``` -### Laravel Valet +You can find the `debug.log` file in the `~/.wp-now/wp-content/${projectName}/` directory. -If you are migrating from Laravel Valet, you should be aware of the differences it has with `wp-now`: +#### Set a custom path for the `debug.log` file -- `wp-now` does not require you to install WordPress separately, create a database, connect WordPress to that database or create a user account. All of these steps are handled by the `wp-now start` command and are running under the hood; -- `wp-now` works across all platforms (Mac, Linux, Windows); -- `wp-now` does not support custom domains or SSL (yet!); -- `wp-now` works with WordPress themes and plugins even if you don't have WordPress installed; -- `wp-now` allows to easily switch the WordPress version with `wp-now start --wp=version.number`(make sure to replace the `version.number` with the actual WordPress version); -- `wp-now` does not support Xdebug PHP extension (yet!) +The `php-wasm` server runs under a VFS where the default `documentRoot` for `wp-now` is always `/var/www/html`. So, a Blueprint executed from a theme named **atlas** would look like this: -Some similarities between Laravel Valet and `wp-now` to be aware of: +```json +{ + "steps": [ + { + "step": "defineWpConfigConsts", + "consts": { + "WP_DEBUG": true, + "WP_DEBUG_LOG": "/var/www/html/wp-content/themes/atlas/example.log" + }, + "method": "define-before-run" + } + ] +} +``` -- could be used for non-WordPress projects; -- deployments are not possible with neither Laravel Valet, nor `wp-now`; -- possible to switch easily the PHP version; -- possibility to work on multiple WordPress sites simultaneously +You can find the `example.log` file in your project's directory. -### wp-env +## Known issues + +- Running `wp-now start` in 'wp-content' or 'wordpress' mode creates empty directories. See [GitHub issue #32](https://github.com/WordPress/playground-tools/issues/32). +- The `wp-now` NPM package may appear to have a random version number. See [GitHub issue #31](https://github.com/WordPress/playground-tools/issues/31). -If you are migrating from `wp-env`, you should be aware of the differences it has with `wp-now`: +## Comparisons -- `wp-now` supports non-WordPress projects; -- `wp-now` does not need Docker; -- `wp-now` does not support Xdebug PHP extension (yet!); -- `wp-now` does not include Jest for automatic browser testing +### Laravel Valet + +Here's what you need to know if you're migrating from Laravel Valet: + +- `wp-now` handles the entire WordPress installation for you. Just run the `wp-now start` command. +- `wp-now` works across all desktop platforms (Mac, Linux, Windows). +- `wp-now` does not set up custom domains for you. +- `wp-now` works with WordPress themes and plugins even if you don't have WordPress installed (see item #1 above). +- `wp-now` allows you to switch the WordPress version with `wp-now start --wp=VERSION_NUMBER`(replace `VERSION_NUMBER` with the actual WordPress version). + +### wp-env -Some similarities between `wp-env` and `wp-now` to be aware of: +Here's what you need to know if you're migrating from `wp-env`: -- no support for custom domains or SSL; -- `plugin`, `themes` and index modes are available on `wp-env` and `wp-now`; -- deployments are not possible with neither `wp-env`, nor `wp-now`; -- possible to switch easily the PHP version +- `wp-now` supports non-WordPress projects. +- `wp-now` does not require Docker. +- `wp-now` does not include Jest for automatic browser testing. ## Contributing We welcome contributions from the community! -In order to contribute to `wp-now`, you'll need to first install a few global dependencies: +### Code contribution -- Make sure you have `nvm` installed. If you need to install it first, - [follow these installation instructions](https://github.com/nvm-sh/nvm#installation). -- Install `nx` by running `npm install -g nx`. - -Once the global dependencies are installed, you can start using the repo: +Clone the repository, install the dependencies, build the project, and start `wp-now` in `preview` mode: ```bash git clone git@github.com:WordPress/playground-tools.git cd playground-tools -nvm use npm install npm run build -nx preview wp-now start --path=/path/to/wordpress-plugin-or-theme +npx nx preview wp-now start ``` -If you'd like to make the `wp-now` executable globally available when using this installation method, run `npm link`. It's not particularly reliable, however. - -## Testing - To run the unit tests, use the following command: ```bash -nx test wp-now -``` - -## Publishing - -The `wp-now` package is part of a larger monorepo, sharing its space with other sibling packages. To publish the `wp-now` package to npm, you must first understand the automated release process facilitated by lerna. This process includes automatically incrementing the version number, creating a new tag, and publishing all modified packages to npm simultaneously. Notably, all published packages share the same version number. - -Each package identifies a distinct organization in its `package.json` file. To publish the `wp-now` package, you need access to the `@wp-now` npm organization. - -To initiate the publishing process for `wp-now`, execute the following commands: - -```bash -npm login # this is required only once and it will store the credentials in ~/.npmrc file. -npm run build -npm run release:wp-now +npx nx test wp-now ``` From 4572345f415d24a49446efdc8f60a89b94fa6a7a Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Thu, 2 May 2024 16:12:32 +0200 Subject: [PATCH 2/6] Clarify wp-now vs. npx @wp-now and update snippets --- packages/wp-now/README.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/packages/wp-now/README.md b/packages/wp-now/README.md index 98fe22f6..285a41fb 100644 --- a/packages/wp-now/README.md +++ b/packages/wp-now/README.md @@ -65,8 +65,6 @@ You can also install `@wp-now/wp-now` globally to run it from any directory: npm install -g @wp-now/wp-now ``` -Lastly, you can install `wp-now` via `git clone`. See [Contributing](#contributing) for more details. - Once installed, start a new server like so: ```bash @@ -74,10 +72,13 @@ cd wordpress-plugin-or-theme wp-now start ``` +> [!IMPORTANT] +> Note the different syntax above. While the preceding `npx @wp-now/` isn't required after installing the package locally, `wp-now ` will produce an error without it. + Use the `--php=` and `--wp=` arguments to switch to different versions on the fly: ```bash -wp-now start --wp=5.9 --php=7.4 +npx @wp-now/wp-now start --wp=5.9 --php=7.4 ``` In supported modes, `wp-now` creates a persistent SQLite database and `wp-content` directory in `~/.wp-now`. @@ -88,7 +89,7 @@ Use `wp-now php ` to execute a specific PHP file: ```bash cd wordpress-plugin-or-theme -wp-now php my-file.php +npx @wp-now/wp-now php my-file.php ``` ### Automatic modes @@ -111,13 +112,13 @@ Here are the heuristics for each mode: You can run `wp-now` with the `--help` flag to get an overview of all the available options. ```bash -wp-now --help +npx @wp-now/wp-now --help # or -wp-now start --help +npx @wp-now/wp-now start --help # or -wp-now php --help +npx @wp-now/wp-now php --help ``` `wp-now start` supports the following optional arguments: @@ -168,7 +169,7 @@ You can prototype and test your Blueprint in a [dedicated online editor](https:/ To run it, create a file named `blueprint-example.json` and run the following command: ```bash -wp-now start --blueprint=path/to/blueprint-example.json +npx @wp-now/wp-now start --blueprint=path/to/blueprint-example.json ``` ### Define custom URLs in a Blueprint @@ -204,7 +205,7 @@ You can use this instance with [`ngrok`](https://ngrok.com/docs): You can also define a different port: ```bash -wp-now start --blueprint=path/to/blueprint-example.json --port=80 +npx @wp-now/wp-now start --blueprint=path/to/blueprint-example.json --port=80 ``` The Blueprint to listen on port `80` would look like this: From e6c9f13571db056d21d353cac4ceadcaf7704e77 Mon Sep 17 00:00:00 2001 From: Ronny Shani Date: Thu, 2 May 2024 16:13:17 +0200 Subject: [PATCH 3/6] Clarify wp-now vs. npx @wp-now and update snippets --- packages/wp-now/README.md | 113 +++++++++++++++++++------------------- 1 file changed, 56 insertions(+), 57 deletions(-) diff --git a/packages/wp-now/README.md b/packages/wp-now/README.md index 285a41fb..2e2c5cb7 100644 --- a/packages/wp-now/README.md +++ b/packages/wp-now/README.md @@ -98,10 +98,8 @@ npx @wp-now/wp-now php my-file.php - **plugin**, **theme**, or **wp-content**: Loads the project files into a virtual filesystem with WordPress and a SQLite-based database. Everything (including WordPress core files, the database, `wp-config.php`, etc.) is stored in the user's home directory and loaded into the virtual file system (VFS). `wp-now` uses the latest WordPress version unless you define the `--wp=` argument. -Here are the heuristics for each mode: - - **plugin** mode: Presence of a PHP file with "Plugin Name:" in its contents. - - **theme** mode: Presence of a `style.css` file with "Theme Name:" in its contents. - - **wp-content** mode: Presence of `plugins` and `themes` subdirectories. +Here are the heuristics for each mode: - **plugin** mode: Presence of a PHP file with "Plugin Name:" in its contents. - **theme** mode: Presence of a `style.css` file with "Theme Name:" in its contents. - **wp-content** mode: Presence of `plugins` and `themes` subdirectories. + - **wordpress**: Runs the directory as a WordPress installation when WordPress files are detected. If it exists, `wp-now` will use the `wp-config.php` file or create one with a SQLite database. - **wordpress-develop**: Same as `wordpress` mode, except the `build` directory is the web root. - **index**: When an `index.php` file is present, `wp-now` starts a PHP web server in the working directory and passes requests to the file. @@ -118,7 +116,7 @@ npx @wp-now/wp-now --help npx @wp-now/wp-now start --help # or -npx @wp-now/wp-now php --help +npx @wp-now/wp-now php --help ``` `wp-now start` supports the following optional arguments: @@ -147,20 +145,20 @@ Below is an example of a Blueprint that runs the latest versions of WordPress an ```json { - "$schema": "https://playground.wordpress.net/blueprint-schema.json", - "landingPage": "/wp-admin/post-new.php", - "preferredVersions": { - "php": "latest", - "wp": "latest" - }, - "phpExtensionBundles": ["kitchen-sink"], - "steps": [ - { - "step": "login", - "username": "admin", - "password": "password" - } - ] + "$schema": "https://playground.wordpress.net/blueprint-schema.json", + "landingPage": "/wp-admin/post-new.php", + "preferredVersions": { + "php": "latest", + "wp": "latest" + }, + "phpExtensionBundles": ["kitchen-sink"], + "steps": [ + { + "step": "login", + "username": "admin", + "password": "password" + } + ] } ``` @@ -184,20 +182,21 @@ Note that the `method` is set to `define-before-run` to avoid modifying the shar ```json { - "steps": [ - { - "step": "defineWpConfigConsts", - "consts": { - "WP_HOME": "http://myurl.wpnow:8881", - "WP_SITEURL": "http://myurl.wpnow:8881" - }, - "method": "define-before-run" - } - ] + "steps": [ + { + "step": "defineWpConfigConsts", + "consts": { + "WP_HOME": "http://myurl.wpnow:8881", + "WP_SITEURL": "http://myurl.wpnow:8881" + }, + "method": "define-before-run" + } + ] } ``` You can use this instance with [`ngrok`](https://ngrok.com/docs): + 1. Run `ngrok http 8881` 2. Copy the URL, and 3. Replace `WP_HOME` and `WP_SITEURL` in the Blueprint file. @@ -212,16 +211,16 @@ The Blueprint to listen on port `80` would look like this: ```json { - "steps": [ - { - "step": "defineWpConfigConsts", - "consts": { - "WP_HOME": "http://myurl.wpnow", - "WP_SITEURL": "http://myurl.wpnow" - }, - "method": "define-before-run" - } - ] + "steps": [ + { + "step": "defineWpConfigConsts", + "consts": { + "WP_HOME": "http://myurl.wpnow", + "WP_SITEURL": "http://myurl.wpnow" + }, + "method": "define-before-run" + } + ] } ``` @@ -233,14 +232,14 @@ Here's the example Blueprint: ```json { - "steps": [ - { - "step": "defineWpConfigConsts", - "consts": { - "WP_DEBUG": true - } - } - ] + "steps": [ + { + "step": "defineWpConfigConsts", + "consts": { + "WP_DEBUG": true + } + } + ] } ``` @@ -262,16 +261,16 @@ The `php-wasm` server runs under a VFS where the default `documentRoot` for `wp- ```json { - "steps": [ - { - "step": "defineWpConfigConsts", - "consts": { - "WP_DEBUG": true, - "WP_DEBUG_LOG": "/var/www/html/wp-content/themes/atlas/example.log" - }, - "method": "define-before-run" - } - ] + "steps": [ + { + "step": "defineWpConfigConsts", + "consts": { + "WP_DEBUG": true, + "WP_DEBUG_LOG": "/var/www/html/wp-content/themes/atlas/example.log" + }, + "method": "define-before-run" + } + ] } ``` From b882d21dfe639280fa297d898960466c6adaa022 Mon Sep 17 00:00:00 2001 From: Ronny Shani <63248335+ironnysh@users.noreply.github.com> Date: Tue, 21 May 2024 15:26:10 +0000 Subject: [PATCH 4/6] Restore mention of `--path=/path/to/wordpress-plugin-or-theme` (see https://github.com/WordPress/playground-tools/pull/251/files/e6c9f13571db056d21d353cac4ceadcaf7704e77#r1598687431) --- packages/wp-now/README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/wp-now/README.md b/packages/wp-now/README.md index 2e2c5cb7..41bdb5dd 100644 --- a/packages/wp-now/README.md +++ b/packages/wp-now/README.md @@ -317,6 +317,11 @@ npm run build npx nx preview wp-now start ``` +> [!TIP] +> Adding the `--path=/path/to/wordpress-plugin-or-theme` argument to the command above is a handy way to test `wp-now` in different modes: +> +> `npx nx preview wp-now start --path=/path/to/wordpress-plugin-or-theme` + To run the unit tests, use the following command: ```bash From 8361e7af423657b87458619893c0702b53209356 Mon Sep 17 00:00:00 2001 From: Ronny Shani <63248335+ironnysh@users.noreply.github.com> Date: Wed, 22 May 2024 13:11:59 +0000 Subject: [PATCH 5/6] Updated comment about Jest support --- packages/wp-now/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/wp-now/README.md b/packages/wp-now/README.md index 41bdb5dd..463cb523 100644 --- a/packages/wp-now/README.md +++ b/packages/wp-now/README.md @@ -299,7 +299,8 @@ Here's what you need to know if you're migrating from `wp-env`: - `wp-now` supports non-WordPress projects. - `wp-now` does not require Docker. -- `wp-now` does not include Jest for automatic browser testing. +- `wp-now` does not include [lifecycle scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/#node-lifecycle-script). + ## Contributing From 6a5f7b0aac7102d69ac483131ff68f4c0d9a572d Mon Sep 17 00:00:00 2001 From: Ronny Shani <63248335+ironnysh@users.noreply.github.com> Date: Wed, 22 May 2024 13:31:38 +0000 Subject: [PATCH 6/6] Create a PUBLISHING.md file with instructions for admins (see https://github.com/WordPress/playground-tools/pull/251#discussion_r1608540532) --- packages/wp-now/PUBLISHING.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 packages/wp-now/PUBLISHING.md diff --git a/packages/wp-now/PUBLISHING.md b/packages/wp-now/PUBLISHING.md new file mode 100644 index 00000000..3d688119 --- /dev/null +++ b/packages/wp-now/PUBLISHING.md @@ -0,0 +1,22 @@ +# Publishing + +The `wp-now` package is part of a larger [monorepo](https://github.com/WordPress/playground-tools), sharing its space with other sibling packages. + +To publish the `wp-now` package to [npm](https://www.npmjs.com/package/@wp-now/wp-now), you must first understand the automated release process facilitated by lerna. + +> [!TIP] +> For more information on Lerna and other tools used in Playground, check out the [Architecture overview](https://wordpress.github.io/wordpress-playground/architecture/index) chapter over on Playground's comprehensive documentation site. + +This process includes automatically incrementing the version number, creating a new tag, and publishing all modified packages to npm simultaneously. Notably, all published packages **share the same version number**. + + Each package identifies a distinct organization in its `package.json` file. + + To publish the `wp-now` package, you need access to the `@wp-now` npm organization. + + To initiate the publishing process for `wp-now`, execute the following commands: + + ```bash + npm login # this is required only once and it will store the credentials in ~/.npmrc file. + npm run build + npm run release:wp-now + ``` \ No newline at end of file