WP Stack is a modern WordPress stack based on Bedrock that helps you get started with the best development tools and project structure.
See Installation/Usage for more details)
- Dependency management with Composer
- Automated deployments with Capistrano
- Better folder structure
- Easy WordPress configuration with environment specific files
- Environment variables with Dotenv
- Easy development environments with VVV
WP Stack is meant as a base for you to fork and modify to fit your needs. It is delete-key friendly and you can strip out or modify any part of it. You'll also want to customize WP Stack with settings specific to your sites/company.
Much of the philosphy behind Bedrock is inspired by the Twelve-Factor App methodology including the WordPress specific version.
Note: While this is a project from the guys behind the Roots starter theme, Bedrock isn't tied to Roots in any way and works with any theme.
- Git
- PHP >= 5.3.2 (for Composer)
- Ruby >= 1.9 (for Capistrano)
If you aren't interested in using a part, then you don't need its requirements either. Not deploying with Capistrano? Then don't worry about Ruby for example.
- Clone/Fork repo inside VVV's
www
directory - Run
composer install
- Answer the questions to generate the
.env
file - Initialize site:
- Fire up VVV by running
vagrant reload --provision
- Or, if it's already running, you can run from within the vagrant environment
./bin/vvv-init.sh -r
- Add theme(s)
- Access WP Admin at
http://<CHOSEN DOMAIN NAME>/wp/wp-admin
- Multisite? run
bin/setup-multisite.sh
- Using Capistrano for deploys?
- Install Capistrano:
gem install capistrano capistrano-composer capistrano-ext railsless-deploy
- Edit stage/environment configs in
config/deploy/
to set the roles/servers and connection options.
├── bin
│ │── mount-bind.sh
│ │── setup-multisite.sh
│ └── vvv-init.sh
├── config
│ │── deploy
│ │ ├── staging.rb
│ │ └── production.rb
│ │── deploy.rb
│ │── environments
│ │ ├── development.php
│ │ ├── staging.php
│ │ └── production.php
│ └── application.php
├── root
│ ├── app
│ │ ├── mu-plugins
│ │ ├── plugins
│ │ └── themes
│ ├── wp
│ ├── index.php
│ └── wp-config.php
├── scripts
├── vendor
├── Capfile
├── Gemfile
├── Gemfile.lock
├── composer.json
└── composer.lock
The organization of WP Stack is similar to putting WordPress in its own subdirectory but with some improvements.
wp-content
(or maybe justcontent
) has been namedapp
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 root because it's required by WP, but it only acts as a loader. The actual configuration files have been moved toconfig/
for better separation.- Capistrano configs are also located in
config/
to make it consistent. vendor/
is where the Composer managed dependencies are installed to.wp/
is where the WordPress core lives. It's also managed by Composer but can't be put undervendor
due to WP limitations.
The root 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.
WP Stack 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. WP Stack considers any 3rd party library as a dependency including WordPress itself and any plugins.
See these two blogs for more extensive documentation:
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
.
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:
!app/plugins/plugin-name
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.
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
You will lose the one-command deploys and built-in integration with Composer. Another deploy method will be needed as well.
- Remove
Capfile
,Gemfile
, andGemfile.lock
- Remove
config/deploy.rb
- Remove
config/deploy/
directory
WP Stack disables the internal WP Cron via define('DISABLE_WP_CRON', true);
. If you keep this setting, you'll need to manually set a cron job like the following in your crontab file:
*/5 * * * * curl http://example.com/wp/wp-cron.php
- Solution for basic database syncing/copying
TODO
TODO