WP Project Manager

A Node CLI tool that simplifies the process of setting up a new WordPress project and development environment.

Dependencies

WP Project Manager depends on the following tools / programs. You'll need to have all of these installed in order for everything to work properly:

• Git
• Node.js
• Composer
• Bower

We also strongly recommend installing:

• Vagrant
• VVV

WP Project Manager uses Vagrant and VVV to create and configure a development environment automatically when you create a new project. If you'd prefer to use your own server environment you can use WP Project Manager without Vagrant or VVV, but you'll need to configure the server and install all dependencies prior to creating your new project. More info on this can be found in the "Usage" section.

macOS / OS X

We recommend using Homebrew and Cask to install and manage dependencies:

# Install Homebrew
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

# Update Git
brew install git

# Install Node and Composer
brew install node
brew install homebrew/php/composer

# Install Bower
npm i -g bower

# Install Vagrant
brew tap caskroom/cask
brew cask install vagrant

If you already installed Node using the standard installer, consider moving the global package location to a user-writable directory. The Node installer sets the global package location to a system directory, which means you need to install global packages (like this one) using sudo. And that's a Very Bad Thing™.

Windows Users

We recommend installing Git for Windows. It will make your life much easier.

GUI Applications

Git

• SourceTree (Mac, Windows)
• GitHub Desktop (Mac, Windows)
• GitKraken (Mac, Windows, Linux)

Vagrant

• Vagrant Manager (Mac, Windows)

Installation

Open up your preferred command line application and enter the following:

npm i -g wp-project-manager

Usage

You can configure settings for your new project one of two ways:

1. Create a project.yml file in your project folder or one of its parents.
2. Specify individual settings via command arguments.

You'll need to specify at least a project title using one of the above methods; the rest will be filled in automatically. You can create a new project.yml using the following command:

wppm config create

The command arguments use dot notation and match the structure of the project.yml file. For example, if you wanted to set a custom theme name, you'd use --theme.name="My Theme Name".

Creating a new project with VVV and Vagrant

If you're using VVV with stock settings, the following would be the simplest way to get a new project up and running:

cd /path/to/vvv/

mkdir www/new-project-folder

cd www/new-project-folder

wppm project create --project.title="My New Project"

cd -

# If the Vagrant box is already running:
vagrant provision

# If the Vagrant box is *not* already running:
vagrant up --provision

After running the above commands, your dev URL would be my-new-project.dev and the theme folder would be located at htdocs/web/app/themes/my-new-project.

Creating a new project on your own server

WP Project Manager requires at least PHP 5.6; we do not support any version of PHP that has reached "end of life" status. You can see which versions of PHP are still officially supported on this page.

If you need to install the dependencies for WP Project Manager on your server, you can use the following commands:

# Update (or install) Node.js
curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get update
sudo apt-get install -y nodejs

# Install Gulp and Bower
npm install -g gulp bower

# Install PHP (you must be using Ubuntu 14.04 or later)
sudo apt-get install php5-fpm php5-cli php5-common php5-dev

# Install Composer
curl -sS https://getcomposer.org/installer | php
chmod +x composer.phar
mv composer.phar /usr/local/bin/composer

# Install WP-CLI
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
mv wp-cli.phar /usr/local/bin/wp

Once you've verified your server meets the minimum requirements and has all of the listed dependencies installed, the next step would be to create a new project folder on your server and create a project.yml file inside that folder:

mkdir /path/to/project/folder

cd /path/to/project/folder

wppm config create

You'll then want to edit your project.yml file and set vvv to false, set a project title, and configure your database info:

vvv: false

project:
  title: Your Project Name

db:
  name:      database-name
  user:      database-user
  pass:      database-password
  host:      host:port
  root_user: root-user
  root_pass: root-password
  prefix:    db_prefix_

Lastly, create your new project and run the WordPress init script:

wppm project create

bash ./scripts/wp-init.sh

Special considerations

• If by chance you already have a program called wppm installed, we've included a wp-project-manager command as well (in fact, wppm is just an alias for wp-project-manager).

• If you plan on sharing a database between your production and development servers, you'll need to set db.prefix in your project config so it matches the prefix used in the production database. You can also use the the --db.prefix argument:

  wppm project create --db.prefix="myprefix_"

• When you create a new project, the various authentication keys and salts used by WordPress internally are automatically generated for you. If you'd prefer to generate these yourself, just visit this URL and copy the block under "Yaml Format", then paste it into your project.yml in the secret section. For example:

  secret:
    auth_key: "..."
    secure_auth_key: "..."
    logged_in_key: "..."
    nonce_key: "..."
    auth_salt: "..."
    secure_auth_salt: "..."
    logged_in_salt: "..."
    nonce_salt: "..."

Project Structure

WP Project Manager uses Bedrock as its base for new projects, which has a different structure than you may be used to. Here's a quick reference:

• Web root: htdocs/web
• WordPress core: htdocs/web/wp
• wp-content: htdocs/web/app
• wp-config: htdocs/config/environments/development.php
• Admin URL: /wp/wp-admin
• Login URL: /wp/wp-login.php

Note that if WP_ENV is set to staging, the config file would be staging.php, and the same for production. This is a convenient way to define environment-specific settings (such as enabling WP_DEBUG for development but not production).