This repository is a start state for a Composer-based WordPress workflow with Pantheon. It is meant to be copied by the the Terminus Build Tools Plugin which will set up for you a brand new
- GitHub repo
- Free Pantheon sandbox site
- A CircleCI configuration to run tests and push from the source repo (GitHub) to Pantheon.
For more background information on this style of workflow, see the Pantheon documentation.
Before running the terminus build:project:create command, make sure you have all of the prerequisites:
- A Pantheon account
- Terminus, the Pantheon command line tool
- The Terminus Build Tools Plugin
- An account with GitHub and an authentication token capable of creating new repos.
- An account with CircleCI and an authentication token.
You may find it easier to export the GitHub and CircleCI tokens as variables on your command line where the Build Tools Plugin can detect them automatically:
export GITHUB_TOKEN=[REDACTED]
export CIRCLE_TOKEN=[REDACTED]
Once you have all of the prerequisites in place, you can create your copy of this repo with one command:
terminus build:project:create pantheon-systems/example-wordpress-composer my-new-site --team="Agency Org Name"
The parameters shown here are:
- The name of the source repo,
pantheon-systems/example-wordpress-composer. If you are interest in other source repos like Drupal 8, see the Terminus Build Tools Plugin. - The machine name to be used by both the soon-to-be-created Pantheon site and GitHub repo. Change
my-new-siteto something meaningful for you. - The
--teamflag is optional and refers to a Pantheon organization. Pantheon organizations are often web development agencies or Universities. Setting this parameter causes the newly created site to go within the given organization. Run the Terminus commandterminus org:listto see the organizations you are a member of. There might not be any.
You will need PHP 7.0 or higher locally to run the build:project:create command as some of the dependencies in this project require it. Both composer.json and pantheon.yml are currently set to use PHP 7.0.
Pantheon will serve the site from the /web subdirectory due to the configuration in pantheon.yml, facilitating a Composer based workflow. Having your website in this subdirectory also allows for tests, scripts, and other files related to your project to be stored in your repo without polluting your web document root.
Even within the /web directory you may notice that other directories and files are in different places compared to a default WordPress installation. See /web/wp-config.php for key settings like WP_SITEURL which allows WordPress core to be relocated to /web/wp. The overall layout of directories in the repo is inspired by Bedrock.
If you are just browsing this repository on GitHub, you may not see some of the directories mentioned above like wp-admin. That is because WordPress core and its plugins are installed via Composer and ignored in the .gitignore file. Specific plugins are added to the project via composer.json and composer.lock keeps track of the exact version of each plugin (or other dependency). Generic Composer dependencies (not WordPress plugins or themes) are downloaded to the /vendor folder. Use the require section for any dependencies you wish to push to Pantheon, even those that might only be used on non-Live environments. Dependencies added in require-dev such as php_codesniffer or phpunit will not be pushed to Pantheon by the CI scripts.
So that CircleCI will have some test to run, this repository includes a configuration of WordHat, A WordPress Behat extension. You can add your own .feature files within /tests/behat/features. A fuller guide on WordPress testing with Behat is forthcoming.
Testing Jenkins Build