• Dependency management with Composer
• Automated deployments with Capistrano
• Better folder 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)

• Git
• PHP >= 5.4
• Ruby >= 1.9 (for Capistrano)

See Documentation for more details on the steps below.

1. Clone/Fork repo
2. Run composer install
3. Copy .env.example to .env and update environment variables:

• DB_NAME - Database name
• DB_USER - Database user
• DB_PASSWORD - Database password
• DB_HOST - Database host (defaults to localhost)
• WP_ENV - Set to environment (development, staging, production, etc)
• WP_HOME - Full URL to WordPress home (http://example.com)
• WP_SITEURL - Full URL to WordPress including subdirectory (http://example.com/wp)

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

Using Capistrano for deploys?

Required Gems:

• capistrano (> 3.1.0)
• capistrano-composer

These can be installed manually with gem install <gem name> but it's highly suggested you use Bundler to manage them. Bundler is basically the Ruby equivalent to PHP's Composer. Just as Composer manages your PHP packages/dependencies, Bundler manages your Ruby gems/dependencies. Bundler itself is a Gem and can be installed via gem install bundler (sudo may be required).

The Gemfile in the root of this repo specifies the required Gems (just like composer.json). Once you have Bundler installed, run bundle install to install the Gems in the Gemfile. When using Bundler, you'll need to prefix the cap command with bundle exec as seen below (this ensures you're not using system Gems which can cause conflicts).

See http://capistranorb.com/documentation/getting-started/authentication-and-authorisation/ for the best way to set up SSH key authentication to your servers for password-less (and secure) deploys.

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

• Edit stage/environment configs in config/deploy/ to set the roles/servers and connection options.

├── Capfile
├── composer.json
├── config
│   ├── application.php
│   ├── deploy
│   │   ├── staging.rb
│   │   └── production.rb
│   ├── deploy.rb
│   └── environments
│       ├── development.php
│       ├── staging.php
│       └── production.php
├── Gemfile
├── vendor
└── docroot
    ├── content
    │   ├── mu-plugins
    │   ├── plugins
    │   └── themes
    ├── wp-config.php
    ├── index.php
    └── wp

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 but these can be whatever you require.

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

Note: You can't re-define constants in PHP. So if you have a base setting in application.php and want to override it in production.php for example, you have a few options:

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

Lab-Kit tries to separate 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 is used to manage dependencies. Lab-Kit considers any 3rd party library as a dependency including WordPress itself and any plugins.

See these two blogs for more extensive documentation:

• Using Composer with WordPress
• WordPress Plugins with Composer

Screencast ($): Using Composer With WordPress

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"

Whenever you add a new plugin or update the WP version, run composer update to install your new packages.

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:

!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 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 we recommend NOT 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.

Composer integration is the biggest part of Lab-Kit, so if you were going to remove it there isn't much point in using Lab-Kit.

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.

It's written in Ruby so it's needed locally if you want to use it. Capistrano was recently rewritten to be completely language agnostic, so if you previously wrote it off for being too Rails-centric, take another look at it.

Screencast ($): Deploying WordPress with Capistrano

Lab-Kit works with WP-CLI just like any other WordPress project would. Previously we required WP-CLI in our composer.json file as a dependency. This has been removed since WP-CLI now recommends installing it globally with a phar file. It also caused conflicts if you tried using a global install.

The wp command will automatically pick up Lab-Kit's subdirectory install as long as you run commands from within the project's directory (or deeper). Lab-Kit includes a wp-cli.yml file that sets the path option to web/wp. Use this config file for any further configuration.

Lab-Kit 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. To remove this functionality, just delete web/app/mu-plugins/riot-autoloader.php.

This enables the use of mu-plugins through Composer if their package type is wordpress-muplugin. You can also override a plugin's type like the following example:

"installer-paths": {
  "web/app/mu-plugins/{$name}/": ["type:wordpress-muplugin", "roots/soil"],
  "web/app/plugins/{$name}/": ["type:wordpress-plugin"],
  "web/app/themes/{$name}/": ["type:wordpress-theme"]
},