WPSites is the fastest way to create a localhost WordPress website.
Just run wpsites create
, select a site template, and give your site a name. Boom. Done.
Check it out:
Demo.mp4
I've been building Independent Analytics for the last 2 years, and during that time I've created hundreds (thousands?) of temporary WordPress sites.
I'd create new sites for development. I'd create new sites to test customer issues. I'd create new sites to track down regression.
It was the same process over and over again. I'd create a new site only to configure it exactly the same way as I'd done countless times before. Enable debug mode. Symlink the local build. Install the plugins we integrate with. The list goes on and on.
No more.
Now I run wpsites create
, select which of my templates I want to use, and wait 10 seconds as the new site is created.
It's sublime.
This has been the most genuily usefull project I've created. I hope you get some value out of it. If you do, say hi. I'd love to hear from you.
You're gonna want to install WPSites as a global composer package. This will give you access to the wpsites
command from anywhere on your machine.
composer global require andrewmead/wpsites
The installation process will place the PHAR executable in ~/.composer/vendor/bin/
. Make sure this directory is part of your PATH, otherwise commands such as wpsites create
will not work.
Before you can create your first WordPress site, you'll need to generate a config file. You can do this by running wpsites config
. This command will copy the default config file to ~/.wpsites.php
.
$ wpsites conifg
Copying default config to `/Users/andrewmead/.wpsites.php`
Config file successfully created!
From here, open the config file in your text editor. There are a couple things you'll need to tweak before you can create your first site.
You need to tell WPSites where on your file system you want it to create new sites. This can be done by changing the value for sites_directory
near the top of ~/.wpsites.php
.
// ~/.wpsites.php
return [
// ...
'sites_directory' => '$HOME/Herd',
// ...
];
The default value of $HOME/Herd
will work if you are using Laravel Herd. If you're using MAMP PRO, you'll need to change the path to $HOME/Sites
.
You can store your sites anywhere, but make sure the site directory is being served up by your localhost server.
Aside from the sites directory, the only other thing you need to configure is your database connection.
There are three options you can use for this. Inside of defaults
, you'll want to use database_host
, database_username
, and database_password
.
By default, WPSites will try to connect to 127.0.0.1:3306
as the user root
. Customize these three values to connect to whatever local MySQL database you're running.
// ~/.wpsites.php
return [
// ...
'defaults' => [
// ...
'database_host' => '127.0.0.1:3306',
'database_username' => 'root',
'database_password' => null,
// ...
]
];
You can test your database connection in the next step by trying to create a new site.
You're now ready to create your first site!
Create your first site by running wpsites create
. You'll be prompted to pick a template, just select "Basic WordPress" for now. We'll talk more about templates a bit later. From there, pick a slug for your site and in a few seconds you should be looking at your brand new WordPress site!
$ wpsites create
┌ Which template would you like to use? ───────────────────────┐
│ › ● Basic WordPress │
│ ○ Basic Multisite WordPress │
│ ○ Symlink plugin example │
│ ○ Bug recreation example │
└──────────────────────────────────────────────────────────────┘
┌ What slug would you like to use? ────────────────────────────┐
│ any-slug-you-like │
└──────────────────────────────────────────────────────────────┘
Downloading core files...
Creating site...
Creating database...
Running installation...
Enabling error log...
Enabling automatic login...
Installing default theme...
Opening site...
Amazing! Now creating your first site is just the beginning. Read on to learn how you can build your own templates to create sites specific to your needs!
there are three top level properties
sites_directory is where news sites are created
defaults define default values for all your sites which is great for things like database connections and maybe not so useful for things like x
templates define an array of site templates to use - in here, you can override any value in defaults to make your sites your own. Array values like plugins will be merged so you can define defaults plugins you always want as well as ones you only want for a specific template.
Let's dig in
The default config files has quite a bit of stuff, but all the defaults properties are only there so you can see all the options you have available.
In reality, you can trim it down quite a bit. Here's the smallest reasonable config file you can get away with. It defines a site directory, a databaes connection, and a couple of simple templates, one a basic site and the other a multisite.
If you liking what you're seeing below, you can absolutely replace your config file with this one. Just make sure to adjust the sites directory and the databae connection options.
<?php
return [
'sites_directory' => '$HOME/Herd',
'defaults' => [
'database_host' => '127.0.0.1:3306',
'database_username' => 'root',
'database_password' => null,
],
'templates' => [
[
'name' => 'Basic WordPress',
],
[
'name' => 'Basic Multisite WordPress',
'enable_multisite' => true,
],
],
];
There are three top-level properties in .wpsites.php
. There's sites_directory
, defaults
, and templates
. This section covers defaults
and templates
.
Let's start with templates
.
The templates
property defines an array of WordPress site templates. The default configuration file comes with a few predefined templates, but you'll definitely want to create and customize your own.
You can create a new template by adding an associative array to the end of templates
. The only thing you have to define is a template name using name
. All other properties are optional.
Your configuration file as contains defaults
. defaults
is an associative array where you can define all of the same properties for a template (except for name
).
So if you wanted ever template to use a specific version of WordPress, such as 5.9.10
, you could define 'wordpress_version' => '5.9.10'
under defaults
instead of needing to define it for every template you create. If there a specific site where you want to use the latest version of WordPress instead, you could set 'wordpress_version' => 'latest'
on the one site template to override the default value.
Let's see this in action. Below is the default .wpsite.php
configuration file. Take a quick look and continue on.
<?php
return [
'sites_directory' => '$HOME/Herd',
'defaults' => [
'wordpress_version' => 'latest',
'database_host' => '127.0.0.1:3306',
'database_username' => 'root',
'database_password' => null,
'database_name' => null,
'admin_username' => 'admin',
'admin_email' => '[email protected]',
'admin_password' => 'password',
'enable_multisite' => false,
'enable_error_logging' => true,
'enable_automatic_login' => true,
'theme' => 'twentytwentyfour',
'plugins' => []
],
'templates' => [
[
'name' => 'Basic WordPress',
],
[
'name' => 'Basic Multisite WordPress',
'enable_multisite' => true,
],
[
'name' => 'Symlink plugin example',
'plugins' => [
'/path/to/symlink/folder',
],
],
[
'name' => 'Bug recreation example',
'wordpress_version' => '5.9.10',
'plugins' => [
'independent-analytics',
],
],
],
];
Under defaults
is every option that you can define. All of these options can be defined on defaults
and also defined on a site template.
You'll notice that the default value for wordpress_version
is latest
. The first 3 site templates don't override this value, so sites created with those templates will use the latest WordPress version.
The last site template overrides the default value for wordpress_version
by settings it own version of wordpress_version
to 5.9.10
.
So you can define a set of reasonable defaults and then override those values on a per template basis.
It's important to note that every default value in defaults
above is the default value for the property. So in this case, the values in defaults
are only there to show you all the options you can set. Since the default value for wordpress_version
is already latest, it's a bit redundant. That means the config file above and the one below are actually the same.
<?php
return [
'sites_directory' => '$HOME/Herd',
'defaults' => [],
'templates' => [
[
'name' => 'Basic WordPress',
],
[
'name' => 'Basic Multisite WordPress',
'enable_multisite' => true,
],
[
'name' => 'Symlink plugin example',
'plugins' => [
'/path/to/symlink/folder',
],
],
[
'name' => 'Bug recreation example',
'wordpress_version' => '5.9.10',
'plugins' => [
'independent-analytics',
],
],
],
];
While every option (except name
) can be set as a default or on a site template, it doesn't always make sense to do so. A good example of this are the database connection options. It's likely that all the sites you create are going to use the same values. You might need to customize it from the defaults, but there's no need to do it on a per site basis copying the same values over and over.
Every option can be set in one of two places. You can set it inside of defaults
to serve as a default for all site templates, or you can set it inside of a site template in templates
to have it be specific to just one template
Option: wordpress_version
Default: 'latest'
The version of WordPress your site will use. Valid values include 'latest', 'nightly', or a WordPress version such as '6.0.0'.
Option: database_host
Default: '127.0.0.1:3306'
The host (and port!) for your sites database connection.
Option: database_username
Default: 'root'
The username for your sites database connection.
Option: database_password
Default: null
The password to for your sites database connection. A value of null should be used if there is no password.
There is no option for defining the database name to create. Instead, the database name comes from the unique slug you pick when creating a WordPress site with wpsites create
.
Option: admin_username
Default: 'admin'
The username for the admin user.
Option: admin_email
Default: '[email protected]'
The email for the admin user.
Option: admin_password
Default: 'password'
The password for the admin user.
Option: enable_multisite
Default: false
Enable to create a multisite. This will also create a second site as part of the multisite network.
Option: enable_error_logging
Default: true
Enable to setup error logging. This sets WP_DEBUG to true, WP_DEBUG_LOG to true, and WP_DEBUG_DISPLAY to false.
Option: enable_automatic_login
Default: true
Enable automatically logging in to the admin panel. This is by installing and configuring the automatic-login plugin.
Option: theme
Default: 'twentytwentyfour'
The slug of the WordPress theme to use. This must be a theme available on the WordPress theme repository. Symlinked themes are currently not supported.
Option: plugins
Default: []
An array of plugins to install.
Use a slug like woocommerce
to install a plugin from the WordPress repository.
Use an absolute path like /plugin/to/symlink
to symlink a local plugin on your machine.
- WPSites uses WP-CLI behind the scenes
- WPSites is not a server and doesn't care how your localhost sites are being served up