    .+?:
     .+??.
       ??? .
       +???.
  +?????????=.
  .???????????.
  .????????????.

 ########### ########
 ############.#######.
 ####### ####  .......
 ######## #### #######
 #########.####.######
 ######  ...
 #######.??.##########
 #######~+??.#########
 ########.??..
 #########.??.#######.
 #########.+?? ######.
           .+?.
     .????????????.
       +??????????,
        .????++++++.
          ????.
          .???,
           .~??.
             .??
              .?,.

Advanced WordPress on Pantheon

Purpose

This repository is an extension of pantheon-systems/example-wordpress-composer showning an example of an advanced WordPress deployment workflow on Pantheon integrating tools such as:

Local development environment with Lando
Asset compilation with gulp 4
PHP dependency management with Composer
Build and testing processes run on CircleCI 2.0
Unit tests with PHP Unit
Behat testing with WordHat
Enforced WordPress coding standards with PHP code sniffer
Performance testing with Lighthouse
Visual regression testing with BackstopJS

Deprecated Branch

The old version of this example used CircleCI 1.0 and did a lot of steps that the Terminus build tools plugin now does manually. This has been deprecated in favor of an example based on CircleCI 2.0 and Example WordPress Composer. The circle-ci-1 branch has this version archived for reference only.

CircleCI Setup

You will need to add the following environment variables in the CircleCI UI. See https://circleci.com/docs/2.0/environment-variables/ for details.

TERMINUS_SITE: Name of the Pantheon site to run tests on, e.g. my_site
TERMINUS_TOKEN: The Pantheon machine token
GITHUB_TOKEN: The GitHub personal access token
GIT_EMAIL: The email address to use when making commits
TEST_SITE_NAME: The name of the test site to provide when installing.
ADMIN_PASSWORD: The admin password to use when installing.
ADMIN_EMAIL: The email address to give the admin when installing.

Local Setup

In order to develop the site locally a few steps need to be completed. These steps only need to be performed once, unless noted.

Open a terminal
Checkout the Git repository
Enter the Git docroot

Local Development

Using Lando as a local development environment

First, take care of the one-time setup steps below:

Install Lando if not already installed
Edit .lando.yml and update name, site and id to match those of your Pantheon site
- You will also need to edit the node proxy if you wish to access BrowserSync at a different URL

Then, use lando start and lando stop to start and stop the local development environment.

After cloning this repository you will need to download dependencies. This can be done through Lando with the commands below:

lando composer-install
lando gulp-build

Tests can also be run locally on Lando with the commands below:

lando composer local-behat
lando composer unit-test

Using another local development environment

All of these steps are a one-time step unless noted.

Install Composer if not already installed
Install NodeJS and NPM if not already installed
Copy sample.env to .env and update the values accordingly
Run ./bin/install-composer-dependencies.sh to install PHP dependencies with Composer
- composer update will need to be ran if composer.json has been changed
Run ./.circleci/build-gulp-assets.sh to compile theme assets

Updates and file changes

** Note: ** if you are using Lando for local development prefix all of the commands below with lando to run them on Lando instead of your local system. For example, npm run dev would become lando npm run dev.

composer update will need to be ran after any changes to composer.json
- Any non-custom PHP code, including to WordPress core, new plugins, etc., should be managed with Composer and updated in this way.
npm run gulp will need to be ran in web/wp-content/themes/twentyseventeen-child after any changes to web/wp-content/themes/twentyseventeen-child/source files
- npm run watch can be used to build the production CSS and JavaScript files, watch for changes in the source files, and rebuild the production files after a change.
- npm run dev is the same as above but it also starts a BrowserSync instance for automated reloading. Be sure to update the url export in web/wp-content/themes/twentyseventeen-child/gulp/constants.js with your local development URL. Unless you are using Lando, in which case leave it set to https://nginx/.
npm install will need to be ran after any changes to web/wp-content/themes/twentyseventeen-child/package.json
- This is for advanced users who wish to customize their frontend build process.

fariasf/Advanced-WordPress-on-Pantheon