@rhildred/wp-now
v0.1.69
Published
WordPress Playground CLI
Downloads
3
Readme
wp-now
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.
Getting Started
To install wp-now
directly from npm
:
npm install -g @wp-now/wp-now
Node 16 is the minimum supported version. Node 20 is required for Blueprint support.
Alternatively, you can install wp-now
via git clone
if you'd like to hack on it too. See Contributing for more details.
Once installed, you can start a new server like so:
cd wordpress-plugin-or-theme
wp-now start
Use the --php=<version>
and --wp=<version>
arguments to switch to different versions on the fly:
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.
Use wp-now php <file>
to execute a specific PHP file:
cd wordpress-plugin-or-theme
wp-now php my-file.php
Automatic Modes
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 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=<version>
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. - wp-content mode: Presence of
plugins
andthemes
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 thebuild
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 theindex.php
. - playground: If no other conditions are matched, launches a completely virtualized WordPress site.
Arguments
wp-now start
currently supports the following arguments:
--path=<path>
: the path to the PHP file or WordPress project to use. If not provided, it will use the current working directory;--php=<version>
: the version of PHP to use. This is optional and if not provided, it will use a default version which is8.0
(example usage:--php=7.4
);--port=<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 to8881
(example of usage:--port=3000
);--wp=<version>
: 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(example usage:--wp=5.8
)--blueprint=<path>
: 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 for more details.--reset
: create a fresh SQLite database and wp-content directory, for modes that support persistence.
Of these, wp-now php
currently supports the --path=<path>
and --php=<version>
arguments.
Technical Details
- The
~/.wp-now
home directory is used to store the WP versions and thewp-content
folders for projects using 'theme', 'plugin', 'wp-content', and 'playground' modes. The path towp-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. The path to SQLite database is~/.wp-now/wp-content/${projectName}-${directoryHash}/database/.ht.sqlite
Using Blueprints
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.
Defining Custom URLs
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.
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 virtualize
is set to true
to avoid modifying the wp-config.php
file that is shared between all the projects.
{
"steps": [
{
"step": "defineWpConfigConsts",
"consts": {
"WP_HOME": "http://myurl.wpnow:8881",
"WP_SITEURL": "http://myurl.wpnow:8881"
},
"virtualize": true
}
]
}
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.
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
The Blueprint to listen on port 80
will look like this:
{
"steps": [
{
"step": "defineWpConfigConsts",
"consts": {
"WP_HOME": "http://myurl.wpnow",
"WP_SITEURL": "http://myurl.wpnow"
},
"virtualize": true
}
]
}
Defining Debugging Constants
In the similar way we can define WP_DEBUG
constants and read the debug logs.
Run wp-now start --blueprint=path/to/blueprint-example.json
where blueprint-example.json
is:
{
"steps": [
{
"step": "defineWpConfigConsts",
"consts": {
"WP_DEBUG": true,
"WP_DEBUG_LOG": true
},
"virtualize": true
}
]
}
This will enable the debug logs and will create a debug.log
file in the ~/.wp-now/wp-content/${project}/debug.log
directory.
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 udner a VFS (virtual file system) where the default documentRoot is always /var/www/html
.
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.
{
"steps": [
{
"step": "defineWpConfigConsts",
"consts": {
"WP_DEBUG_LOG": "/var/www/html/wp-content/themes/atlas/example.log"
},
"virtualize": true
}
]
}
Known Issues
- Running
wp-now start
in 'wp-content' or 'wordpress' mode will produce some empty directories: WordPress/wordpress-playground#328 - Inline images are broken when site starts on a different port: WordPress/wordpress-playground#356
wp-now
doesn't build or start on Windows: WordPress/playground-tools#66, WordPress/playground-tools#11- Pretty permalinks aren't yet supported: WordPress/playground-tools#53
- It's not possible to set
WP_DEBUG
and otherwp-config.php
constants: WordPress/playground-tools#17 - In 'wordpress' mode,
wp-now
can connect to a MySQL database withdefine( 'DB_HOST', '127.0.0.1' );
, butdefine( 'DB_HOST', 'localhost' );
does not work: WordPress/wordpress-playground#369 wp-now
published versions can appear random: WordPress/wordpress-playground#357
Comparisons
Laravel Valet
If you are migrating from Laravel Valet, you should be aware of the differences it has with wp-now
:
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 thewp-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 withwp-now start --wp=version.number
(make sure to replace theversion.number
with the actual WordPress version);wp-now
does not support Xdebug PHP extension (yet!)
Some similarities between Laravel Valet and wp-now
to be aware of:
- 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
wp-env
If you are migrating from wp-env
, you should be aware of the differences it has with wp-now
:
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
Some similarities between wp-env
and wp-now
to be aware of:
- no support for custom domains or SSL;
plugin
,themes
and index modes are available onwp-env
andwp-now
;- deployments are not possible with neither
wp-env
, norwp-now
; - possible to switch easily the PHP version
Contributing
We welcome contributions from the community!
In order to contribute to wp-now
, you'll need to first install a few global dependencies:
- Make sure you have
nvm
installed. If you need to install it first, follow these installation instructions. - Install
nx
by runningnpm install -g nx
.
Once the global dependencies are installed, you can start using the repo:
git clone [email protected]: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
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:
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:
npm login # this is required only once and it will store the credentials in ~/.npmrc file.
npm run build
npm run release:wp-now