WordPress Bootstrap (Based on Bedrock)

Bedrock is a modern WordPress stack that helps we are using as a starting point for our WordPress Projects. It includes the best practices for development and project structure.

Table of Contents

• Quick Start
• Features
• Required
• Installation/Usage
  • via Composer
  • Manually
• Deploying with Capistrano
  • Steps
• Documentation
  • Folder Structure
  • Configuration Files
  • Environment Variables
  • Composer
  • Capistrano
  • WP-CLI
  • Vagrant/Ansible
• Contributing
• Support

Features

• Dependency management with Composer
• Automated deployments with Capistrano
• Better directory structure
• Easy WordPress configuration with environment specific files
• Environment variables with Dotenv
• Autoloader for mu-plugins (let's you use regular plugins as mu-plugins)

Much of the philosphy behind Bedrock is inspired by the Twelve-Factor App methodology including the WordPress specific version.

Requirements

• Git
• PHP >= 5.3.2 (for Composer)
• Ruby >= 1.9 (for Capistrano)
• Required Gems:
  • bundler
  • capistrano (> 3.1.0)
  • capistrano-composer

Installation

See Documentation for more details on the steps below.

Using the Composer create-project command

This will automatically install the Bedrock package to the specified path and run composer install.The post-install script will automatically copy .env.example to .env and you'll be prompted about generating salt keys and appending them to your .env file.

NOTE: To generate salts without a prompt, run create-project with -n (non-interactive).

1. Run composer create-project roots/bedrock <path> (path being the folder to install to)
2. Edit .env and update environment variables:

• DB_NAME - Database name
• DB_USER - Database user
• DB_PASSWORD - Database password
• DB_HOST - Database host (defaults to localhost)
• DB_TABLE_PREFIX - Database table prefix (set to something other than wp_ e.g. wp6Jid5i9s_)
• WP_ENV - Set to environment (development, staging, production, etc)
• WP_HOME - Full URL to WordPress home (http://site.com)
• WP_SITEURL - Full URL to WordPress including subdirectory (http://site.com/wp)
• ADMIN_EMAIL - Admin email for the project
• BLOG_NAME - Site Title
• BLOG_DESCRIPTION - Site Description

3. Add theme(s)
4. Set Nginx or Apache vhost to /path/to/site/current/web/
5. Access WP Admin at http://site.com/wp/wp-admin

Deployment

1. Edit the config/deploy/ environment configs to set the roles/servers and connection options.
2. Before the first deploy, run bundle exec cap <stage> deploy:check to create the necessary folders/symlinks.
3. Add the .env file to shared/ in the deploy_to path on the remote server for all the stages you use (ex: /path/to/site/shared/.env)
4. Run the deploy command: bundle exec cap <stage> deploy

Documentation

Folder Structure

├── config
│   ├── application.php
│   ├── deploy.rb
│   ├── deploy
│   │   ├── production.rb
│   │   └── staging.rb
│   └── environments
│       ├── development.php
│       ├── production.php
│       └── staging.php
├── scripts
│   └── Roots
│       └──Bedrock
│          └── installer.php
├── vendor
├── web
│   ├── app
│   │   ├── mu-plugins
│   │   │   ├── bedrock-autoloader.php
│   │   │   ├── disallow-indexing.php
│   │   │   └── register-theme-directory.php
│   │   ├── plugins
│   │   └── themes
│   ├── index.php
│   ├── wp-config.php
│   └── wp
├── .env.example
├── .gitignore
├── Capfile
├── composer.json
├── Gemfile
├── LICENSE.md
├── README.md
└── wp-cli.yml

The organization of Bedrock is similar to putting WordPress in its own subdirectory but with some improvements.

• In order not to expose sensitive files in the webroot, Bedrock moves what's required into a web/ directory including the vendor'd wp/ source, and the wp-content source.
• wp-content (or maybe just content) has been named app to better reflect its contents. It contains application code and not just "static content". It also matches up with other frameworks such as Symfony and Rails.
• wp-config.php remains in the web/ because it's required by WP, but it only acts as a loader. The actual configuration files have been moved to config/ for better separation.
• Capistrano configs are also located in config/ to make it consistent.
• vendor/ is where the Composer managed dependencies are installed.
• wp/ is where the WordPress core lives. It's also managed by Composer but can't be put under vendor due to WP limitations.

Configuration Files

The root web/wp-config.php is required by WordPress and is only used to load the other main configs. Nothing else should be added to it.

config/application.php is the main config file that contains what wp-config.php usually would. Base options should be set in there.

For environment specific configuration, use the files under config/environments. By default there's is development, staging, and production.

The environment configs are required before the main application config so anything in an environment config takes precedence over application.

Constants can't be re-define in PHP, so if there is a base setting in application.php and it needs to be overridden in production.php for example, there are really only two options:

1. Remove the base option and be sure to define it in every environment it's needed
2. Only define the constant in application.php if it isn't already defined.

Environment Variables

Bedrock separates config from code as much as possible and environment variables are used to achieve this. The benefit is there's a single place (.env) to keep settings like database or other 3rd party credentials that isn't committed to your repository.

PHP dotenv is used to load the .env file. All variables are then available in your app by getenv, $_SERVER, or $_ENV.

Currently, the following env vars are required:

• DB_USER
• DB_NAME
• DB_PASSWORD
• WP_HOME
• WP_SITEURL

Composer

Composer is used to manage dependencies. Bedrock considers any 3rd party library as a dependency including any plugins and WordPress itself.

See the following for more extensive documentation:

• Using Composer with WordPress
• WordPress Plugins with Composer
• Using Composer With WordPress

Managing WP Plugins

WordPress Packagist is already registered in the composer.json file so any plugins from the WordPress Plugin Directory can easily be required.

To add a plugin, add it under the require directive or use composer require <namespace>/<packagename> from the command line. If it's from WordPress Packagist then the namespace is always wpackagist-plugin.

Example: "wpackagist-plugin/akismet": "dev-trunk"

plugins, and mu-plugins are Git ignored by default since Composer manages them. If you want to add something to those folders that isn't managed by Composer, you need to update .gitignore to whitelist them like so:

!web/app/plugins/plugin-name

NOTE: Some plugins may create files or folders outside of their given scope, or even make modifications to wp-config.php and other files in the app directory. These files should be added to your .gitignore file as they are managed by the plugins themselves, which are managed via Composer. Any modifications to wp-config.php that are needed should be moved into config/application.php.

Updating your WordPress version (or any plugin) is just a matter of changing the version number in the composer.json file. Then running composer update will pull down the new version.

Themes

Themes can also be managed by Composer but should only be done so under two conditions:

1. You're using a parent theme that won't be modified at all
2. You want to separate out your main theme and use that as a standalone package

Under most circumstances it is NOT recommend doing #2 and instead keeping your main theme as part of your app's repository.

Just like plugins, WPackagist maintains a Composer mirror of the WP theme directory. To require a theme, just use the wpackagist-theme namespace.

Capistrano

Capistrano is a remote server automation and deployment tool. It will let you deploy or rollback your application in one command:

• Deploy: cap production deploy
• Rollback: cap production deploy:rollback

Composer support is built-in so when you run a deploy, composer install is automatically run. Capistrano has a great deploy flow that you can hook into and extend it.

NOTE: For more details checkout Deploying WordPress with Capistrano

wp-cron

Bedrock disables the internal WP Cron via define('DISABLE_WP_CRON', true);. If your project disables this setting, you'll need to manually set a cron job like the following in the crontab file:

*/5 * * * * curl http://example.com/wp/wp-cron.php

WP-CLI

Bedrock works with WP-CLI just like any other WordPress project would. The wp command will automatically pick up the subdirectory install as long as commands are run from within the project's directory (or deeper). Bedrock includes a wp-cli.yml file that sets the path option to web/wp. Use this config file for any further configuration.

bedrock-autoloader.php

Bedrock includes an autoloader that enables standard plugins to be required just like must-use plugins. The autoloaded plugins are included after all mu-plugins and standard plugins have been loaded. An asterisk (*) next to the name of the plugin designates the plugins that have been autoloaded.

Todo

• Solution for basic database syncing/copying

Additional Support

Use the Roots Discourse forum to ask questions and get support.