🚂 WordPress Project Boilerplate

A quick and opinionated WordPress boilerplate with Composer, an easier configuration, and an improved folder structure.

This boilerplate is based on wp-jazz/wp-project-skeleton which is derived from Bedrock.

If you have the capability, please consider sponsoring Roots.

Overview

This boilerplate assumes you are familiar with wp-jazz/wp-project-skeleton and Bedrock.

Differences with wp-jazz/wp-project-skeleton:

• The Web root directory is www instead of public.
• Includes a copy of wp-ajax.php, a near-identical copy of WordPress' admin-ajax.php.
• Prepared for integration with:
  • Activity Log — Plugin to monitor and log all changes and activities.
  • Advanced Custom Fields Pro — Plugin to allow adding extra content fields.
  • Ecocide — Library to disable basic features of WordPress.
  • Gravity Forms — Plugin to allow building custom forms.
  • Polylang Pro — Plugin to support multilingual content.
• Includes copies of WordPress databases:
  • Unilingual (English)
  • Multilingual (English and French)

Requirements

• PHP >= 7.4
• Composer (Installation)
• Active licenses for Advanced Custom Fields Pro, Gravity Forms, and Polylang Pro.

Installation

1. Create a new project:

   composer create-project locomotivemtl/wordpress-boilerplate

   Note that installation of Composer dependencies will fail because of the premium WordPress plugins that require license keys to be defined.

   Alternatively, clone the repository:

   git clone https://github.com/locomotivemtl/wordpress-boilerplate.git .
   rm -rf .git
   git init
   git add -A
   git commit -m "Initial commit"

   Or add the repository as a remote:

   git remote add boilerplate https://github.com/locomotivemtl/wordpress-boilerplate.git
   git fetch boilerplate main
   git merge boilerplate/main

2. Update environment variables in the .env file.

   Wrap values that may contain non-alphanumeric characters with quotes, or they may be incorrectly parsed.

   • Database variables:
     • DB_NAME — Database name
     • DB_USER — Database user
     • DB_PASSWORD — Database password
     • DB_HOST — Database host
     • Optionally, you can define DATABASE_URL for using a DSN instead of using the variables above (e.g. mysql://user:password@127.0.0.1:3306/db_name)
   • WP_DEVELOPMENT_MODE — Set the development mode (all for development or empty string for production)
   • WP_ENVIRONMENT_TYPE — Set to environment (development, staging, production)
   • WP_HOME — Full URL to WordPress home (https://example.com)
   • WP_SITEURL — Avoid editing this variable. Full URL to WordPress including subdirectory (https://example.com/wordpress)
   • ACF_PRO_KEY, GRAVITY_FORMS_KEY, POLYLANG_PRO_KEY — Premium plugin license keys.
   • AUTH_KEY, SECURE_AUTH_KEY, LOGGED_IN_KEY, NONCE_KEY, AUTH_SALT, SECURE_AUTH_SALT, LOGGED_IN_SALT, NONCE_SALT
     • Generate with wp-cli-dotenv-command
     • Generate with our WordPress salts generator

3. Supply Composer with credentials for authenticating the installation of Polylang Pro:

   This step is necessary because Polylang Pro uses Easy Digital Downloads (EDD) for distribution.

   composer config [--global] --editor --auth

   {
       "http-basic": {
           "polylang.pro": {
               "username": "username",
               "password": "password"
           }
       }
   }

4. Add plugin(s) in www/plugins and www/mu-plugins, and theme(s) in www/themes either:

   • as you would for a normal WordPress site (add an exception to the .gitignore if you want to index them)
   • or as Composer dependencies.

5. Most projects use pretty permalinks. This requires a .htaccess file on Apache servers. This file is not indexed in Git since it can contain environment-specific requirements. To create or update the file (and update rewrite rules in the database):

   wp rewrite flush --hard

6. Set the document root on your Web server to Jazz's www folder: /path/to/site/www/.

7. Access WordPress admin at https://example.com/wordpress/wp-admin/.

If you choose to use one of the starting databases, you will need to change the following:

• Replace the base URI:
  • example.test
• Add your license keys:
  • acf_pro_license
  • rg_gforms_key
  • rg_gforms_captcha_public_key
  • rg_gforms_captcha_private_key

Contributing

Contributions are welcome from everyone. We have contributing guidelines to help you get started.

Acknowledgements

This boilerplate is based on the solid work of many that have come before me, including:

• Bedrock
• wp-jazz/wp-project-skeleton