From b130235adadedc9392339c7a21abf09b43437cfb Mon Sep 17 00:00:00 2001 From: Chris Reynolds Date: Tue, 15 Oct 2024 13:35:56 -0600 Subject: [PATCH] [SITE-988] Consolidate WordPress Composer Build Tools docs with the regular Build Tools docs (#9236) * Move most of the build-tools content for WP into the Build Tools create project doc * [SITE-988] Consolidate WordPress Composer multisite config doc with the existing Multisite Configuration doc (#9260) * delete the multisite config guide under wordpress-composer * add relevant info from the wpcm multisite config to the main multisite config guide * [SITE-988] Consolidate WPCM Custom Upstream documentation with the existing IC custom upstream documentation (#9261) * update ic-upstream-structure partial to match wpcm * add contributor and bump reviewed date * update wpcm link * add additional (cms-agnostic) info from wpcm ic doc * add additional resources (from wpcm cu doc) * delete the wpcm ic doc --- .../guides/build-tools/02-create-project.md | 197 ++++++++++++--- .../integrated-composer/06-ic-upstreams.md | 37 ++- source/content/guides/multisite/03-config.md | 46 +++- ...03-create-wp-site-composer-ci-auto-test.md | 235 ------------------ .../04-multisite-configuration.md | 72 ------ .../wordpress-composer/06-wordpress-ic.md | 80 ------ .../content/partials/ic-upstream-structure.md | 8 +- 7 files changed, 242 insertions(+), 433 deletions(-) delete mode 100644 source/content/guides/wordpress-composer/03-create-wp-site-composer-ci-auto-test.md delete mode 100644 source/content/guides/wordpress-composer/04-multisite-configuration.md delete mode 100644 source/content/guides/wordpress-composer/06-wordpress-ic.md diff --git a/source/content/guides/build-tools/02-create-project.md b/source/content/guides/build-tools/02-create-project.md index 5e89216337..523ffa2fd7 100644 --- a/source/content/guides/build-tools/02-create-project.md +++ b/source/content/guides/build-tools/02-create-project.md @@ -2,11 +2,11 @@ title: Build Tools subtitle: Create a New Project description: In step two of the Build Tools guide, learn how to create a new Build Tools project. -tags: [composer, terminus, webops, workflow, D8, D9, D10] +tags: [composer, terminus, webops, workflow, D8, D9, wordpress] type: guide permalink: docs/guides/build-tools/create-project/ editpath: build-tools/02-create-project.md -reviewed: "2021-12-13" +reviewed: "2024-09-26" contenttype: [guide] innav: [false] categories: [dependencies] @@ -16,7 +16,7 @@ product: [--] integration: [--] --- -In this section, we will use the Terminus Build Tools Plugin to create a new project consisting of a Git repository, a Continuous Integration service, and a Pantheon site. +In this section, we will use the Terminus Build Tools Plugin to create a new project consisting of a Git repository, [Composer](https://getcomposer.org), a Continuous Integration (CI) service, and a Pantheon site with Automated Testing. This guide will get you started, but you will need to customize and maintain the CI/testing set up for your projects. @@ -26,35 +26,14 @@ Substitute your chosen Git Provider and CI service in these instructions with th -## Prerequisites +## Requirements -Ensure you have the latest versions of Terminus and the Terminus Build Tools plugin installed. You may want to run `terminus self:plugin:update pantheon-systems/terminus-build-tools-plugin` to ensure you have the most recent version. - -1. Install [Composer](/guides/composer). - - Verify your installation with `composer --version`: - - ```bash{outputLines: 2} - composer --version - Composer version 2.1.8 2021-09-15 13:55:14 - ``` - -1. Install the most recent release of [Terminus](/terminus/). - - Verify your installation with `terminus --version`: - - ```bash{outputLines: 2} - terminus --version - Terminus 3.0.1 - ``` - -1. [Add an SSH key](/ssh-keys) in your Personal Workspace. - -1. [Generate a Pantheon machine token](https://dashboard.pantheon.io/machine-token/create), then authenticate Terminus. - -1. Install the [Terminus Build Tools Plugin](https://github.com/pantheon-systems/terminus-build-tools-plugin): - - ```bash{promptUser: user} - terminus self:plugin:install terminus-build-tools-plugin - ``` +* [Composer](/guides/integrated-composer) +* [Terminus](/terminus/) +* [Terminus Build Tools Plugin](https://github.com/pantheon-systems/terminus-build-tools-plugin) +* [PHP version](https://docs.pantheon.io/guides/php/php-versions#verify-current-php-versions) 7.2 or greater +* [An SSH key](/ssh-keys) in your Personal Workspace. +* [A Pantheon machine token](https://dashboard.pantheon.io/machine-token/create), to authenticate Terminus. ### Access Tokens (Optional) @@ -119,16 +98,172 @@ Modify the commands in the following examples to match your project's needs. terminus build:project:create --git=github --team='My Agency Name' wp my-site ``` + + +Pantheon has a [WordPress (Composer Managed)](/guides/wordpress-composer/wordpress-composer-managed) upstream. You can use this upstream to create a Composer-managed WordPress site with **Bedrock**. **Terminus Build Tools** does not currently support the Bedrock-based WordPress (Composer Managed) upstream. + + + - Start a GitHub project with Drupal: ```bash{promptUser: user} terminus build:project:create --git=github --team='My Agency Name' d9 my-site ``` + + + +Support has not yet been added for Drupal versions past 9, however you can still update to the latest Drupal version after creating the project. + + The script will ask for additional information such as tokens/credentials for GitHub and the associated CI. For a list of all available command options, see the [Build Tools Project README](https://github.com/pantheon-systems/terminus-build-tools-plugin/blob/3.x/README.md#buildprojectcreate) +## Review Important Directories and Update File Paths + +### `/web` Directory + +Your site is stored and served from the `/web` subdirectory located next to the `pantheon.yml` file. You must store your website in this subdirectory for a Composer-based workflow. Placing your website in the subdirectory also allows you to store tests, scripts, and other files related to your project in your repo without affecting your web document root. It also provides additional security by preventing web access to files outside of the document root through Pantheon. +Your files may still be accessible from your version control project if it is public. See the [`pantheon.yml` documentation](/pantheon-yml#nested-docroot) for details. + +1. Verify that your website is stored in the `/web` subdirectory. + +### `composer.json` File + +This project uses Composer to manage third-party PHP dependencies. Some files, such as core CMS packages inside the `/web` directory, may not be visible in the repository. This is because the CMS (Drupal or WordPress) and its plugins/modules are installed via Composer and ignored in the `.gitignore` file. + +Third-party dependencies, such as modules, plugins and themes, are added to the project via `composer.json` file. The `composer.lock` file keeps track of the exact dependency version. For WordPress, Composer installer-paths are used to ensure the dependencies are downloaded into the appropriate directory. + +1. Place all dependencies in the **require** section of your `composer.json` file. + + - This includes dependencies that are only used in non-Live environments. All dependencies in the **require** section are pushed to Pantheon. + +1. Place all dependencies that are not a part of the web application but are necessary to build or test the project in the **require-dev** section. + + - Example dependencies are `php_codesniffer` and `phpunit`. Dev dependencies are deployed to Dev and Multidev environments, but not to Test and Live environments. + +## Continuous Integration + +The scripts that run on Continuous Integration are stored in the `.ci` directory. Provider-specific configuration files, such as `.circle/config.yml` and `.gitlab-ci.yml` use these scripts. + +The scripts are organized into subdirectories according to their function: + +- Build +- Deploy +- Test + +### Build Scripts .ci/build + +- `.ci/build` script builds an artifact suitable for deployment. + +- `.ci/build/php` installs PHP dependencies with Composer. + +### Build Scripts `.ci/deploy` + +All scripts stored in the `.ci/deploy` directory facilitate code deployment to Pantheon. + + - `.ci/deploy/pantheon/create-multidev` creates a new [Pantheon Multidev environment](/guides/multidev) for branches other than the default Git branch. Note that not all users have Multidev access. Please consult the [Multidev FAQ doc](/guides/multidev/multidev-faq) for details. + +- `.ci/deploy/pantheon/dev-multidev` deploys the built artifact to either the Pantheon Dev or a Multidev environment, depending on the Git branch. + +## Automated Test Scripts `.ci/tests` + +The `.ci/tests` scripts run automated tests. You can add or remove scripts depending on your testing needs. + +### Static Testing + +- `.ci/test/static` and `tests/unit` are static tests that analyze code without executing it. These tests are good at detecting syntax errors but not functionality errors. + +- `.ci/test/static/run` runs [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) with [WordPress coding standards](https://github.com/WordPress/WordPress-Coding-Standards) (for WordPress sites), [PHP Unit](https://phpunit.de/), and [PHP syntax checking](https://phpcodechecker.com/). + +- `tests/unit/bootstrap.php` bootstraps the Composer autoloader. + +- `tests/unit/TestAssert.php` provides an example Unit test. + +1. Create all project-specific test files in the `tests/unit` directory. + +### Visual Regression Testing + +The scripts stored in the `.ci/test/visual-regression` directory run visual regression testing through a headless browser to take screenshots of web pages and compare them for visual differences. + +- `.ci/test/visual-regression/run` runs [BackstopJS](https://github.com/garris/BackstopJS) visual regression testing. + +- `.ci/test/visual-regression/backstopConfig.js` is the [BackstopJS](https://github.com/garris/BackstopJS) configuration file. + +1. Update the settings in `.ci/test/visual-regression/backstopConfig.js` file for your project. + + - For example, the `pathsToTest` variable determines the URLs to test. + +## GitHub Actions + +This section provides information enabling GitHub Actions for your site. + +The Build Tools Site will configure GitHub Actions automatically if it was passed as the selected CI when creating the site. You will need to consult advanced external resources if you're working with an existing non-Build Tools site and want to add Github Actions. + +The steps to enable GitHub Actions for an existing Build Tools site created with another CI (for example, CircleCI) shown below might work for you. + +1. Copy `.ci/.github` to `.github`. + +1. Add the following secrets to the Github Actions configuration: + + - `ADMIN_EMAIL` + + - `ADMIN_PASSWORD` + + - `ADMIN_USERNAME` + + - `TERMINUS_TOKEN` + + - `TERMINUS_SITE` + + - `SSH_PRIVATE_KEY` + + - `GH_TOKEN` + + +## Working Locally with Lando + +Complete the one-time steps below to get started using [Lando](https://docs.devwithlando.io/) for local development. Please note than Lando is an independent product and is not supported by Pantheon. Refer to the [Lando documentation](https://docs.devwithlando.io/) for more information. + +1. [Install Lando](https://docs.lando.dev/getting-started/installation.html) if it is not already installed. + +1. Clone your project repository from GitHub to your local. + +1. Manually create a `.lando.yml` file with your preferred configuration, based on the WordPress recipe. + +1. Run `lando start` to start Lando. + +1. Save the local site URL. + + - The local site URL should look similar to: `https://.lndo.site.` + +1. Run the command below to download dependencies. + + ```bash + `lando composer install --no-ansi --no-interaction --optimize-autoloader --no-progress` + ``` + +1. Run the command below to download the media files and database from Pantheon. + + ```bash + `lando pull --code=none` + ``` + +1. Visit the local site URL saved in the preceding steps. + + - You should now be able to edit your site locally. The steps above do not need to be completed on subsequent starts. You can stop Lando with `lando stop` and start it again with `lando start`. + +1. Run all Composer, Terminus and wp-cli commands in Lando instead of the host machine. + + - This is done by prefixing the desired command with `lando`. For example, after a change to `composer.json` run `lando composer update` rather than `composer update`. + + + +Do NOT push/pull code between Lando and Pantheon directly. All code should be pushed to GitHub and deployed to Pantheon through a continuous integration service, such as CircleCI. + + + ### Troubleshooting diff --git a/source/content/guides/integrated-composer/06-ic-upstreams.md b/source/content/guides/integrated-composer/06-ic-upstreams.md index 6a708d7641..3a3ace365a 100644 --- a/source/content/guides/integrated-composer/06-ic-upstreams.md +++ b/source/content/guides/integrated-composer/06-ic-upstreams.md @@ -3,8 +3,8 @@ title: Integrated Composer subtitle: Custom Upstream Usage description: Learn how to use an Upstream with Integrated Composer. tags: [composer, workflow] -contributors: [ari, edwardangert] -reviewed: "2022-12-13" +contributors: [ari, edwardangert, jazzsequence] +reviewed: "2024-10-15" showtoc: true permalink: docs/guides/integrated-composer/ic-upstreams contenttype: [guide] @@ -21,7 +21,7 @@ This section provides usage and maintanenance information for composer-managed [ ## Custom Upstreams -An Upstream refers to the source code in Git that shares a Git history with "downstream" individual sites made from it. Upstreams includes the core code for [Drupal](https://github.com/pantheon-upstreams/drupal-composer-managed), [WordPress](https://github.com/pantheon-upstreams/wordpress-project), and some customizations for the Pantheon platform. +An Upstream refers to the source code in Git that shares a Git history with "downstream" individual sites made from it. Upstreams includes the core code for [Drupal](https://github.com/pantheon-upstreams/drupal-composer-managed), [WordPress](https://github.com/pantheon-upstreams/wordpress-composer-managed), and some customizations for the Pantheon platform. ### Custom Upstream and Site Structure @@ -29,12 +29,37 @@ An Upstream refers to the source code in Git that shares a Git history with "dow +## Create Your Integrated Composer Custom Upstream + +Follow the steps in this section to create a custom upstream that uses Integrated Composer. + +1. Fork the Pantheon-maintained [WordPress (Composer Managed)](https://github.com/pantheon-upstreams/wordpress-composer-managed) or [Drupal Composer Managed](https://github.com/pantheon-upstreams/drupal-composer-managed) upstream repository. + +1. [Connect your repository](/guides/custom-upstream/create-custom-upstream#connect-repository-to-pantheon) to Pantheon. + +1. Update the **require** section of the root `/composer.json` file to match the name you chose in the preceding step. + +## Add and Remove Packages + +1. Use `composer require`in the `upstream-configuration` directory (or `composer upstream-require` if using `upstream-management`) to edit the upstream `composer.json` file. + - The WordPress (Composer Managed) repository places a theme in the upstream `composer.json` file. This works well for downstream sites that all use the same theme. You should remove themes from the upstream `composer.json` file if you do not intend to use the upstream to lock downstream sites into a particular theme. You cannot remove installed packages from downstream sites if the packages were included from the upstream site. + +## Maintain Your Integrated Composer Fork + + There are some special considerations to keep in mind if you intend to make modifications to your upstream based on this repository. + +1. Increase the version number listed in the `upstream-configuration/composer.json` file each time you make edits. + - Composer checks the contents of the root `/composer.json` file for changes that should be pushed to your upstream configuration. + +1. Verify your changes to the `upstream-configuration/composer.json` file by running `composer install` or `composer update` in the `upstream-configuration` directory. + - Be careful not to rely on ["root-only" properties of composer.json](https://getcomposer.org/doc/04-schema.md). + ## More Resources - [Custom Upstreams](/guides/custom-upstream) - - [Autopilot for Custom Upstreams](/guides/autopilot-custom-upstream) - - [Migrate a Custom Upstream to Drupal](/guides/drupal-hosted-createcustom) - - [Pantheon YAML Configuration Files](/pantheon-yml) +- [Best Practices for Maintaining Custom Upstreams](/guides/custom-upstream/maintain-custom-upstream) +- [Composer Fundamentals and WebOps Workflows](/guides/composer) +- [Create a Composer-managed WordPress Site with Bedrock](/guides/wordpress-composer/wordpress-composer-managed) diff --git a/source/content/guides/multisite/03-config.md b/source/content/guides/multisite/03-config.md index 5c9b132ea4..9a08b1b4a0 100644 --- a/source/content/guides/multisite/03-config.md +++ b/source/content/guides/multisite/03-config.md @@ -132,6 +132,42 @@ Complete the steps below after spinning up a new WPMS site from the correct Cust /* That's all, stop editing! Happy Pressing. */ ``` +## Setting up Multisite on WordPress (Composer Managed) sites + +The [Bedrock](https://roots.io/bedrock/)-based [WordPress (Composer Managed)](https://github.com/pantheon-systems/wordpress-composer-managed) upstream uses `Config::define()` and `config/application.php` instead of traditional `define()` statements in `wp-config.php`. You will not be able to use WP-CLI via Terminus to enable multisite as documented above in a standard multisite configuration. This section provides guidance on how to set up a WordPress Multisite using the WordPress (Composer Managed) upstream. + +1. Set the site's connection mode to Git: + + ```bash{promptUser: user} + terminus connection:set .dev git + ``` +2. Open the `config/application.php` file in your site's codebase and add the following line anywhere _above_ the `Config::apply();` line: + + ```php + Config::define( 'WP_ALLOW_MULTISITE', true ); + ``` +3. Visit your development site's WordPress admin and navigate to **Tools** > **Network Setup**. + ![Network Setup page](../../../images/wordpress-composer/04-multisite-network-setup.png) +4. Choose **Sub-domains** or **Sub-directories** (depending on your needs), fill in the Network Title and Admin Email, and click **Install**. +5. You will be given instructions to update your `config/application.php` file. Below where you added the `WP_ALLOW_MULTISITE` line, copy and paste the code provided. The `SUBDOMAIN_INSTALL` value will be `true` or `false` depending on the option you chose in the previous step. For example, if you chose subdirectories, your `config/application.php` file should look like this: + + ```php + Config::define( 'MULTISITE', true ); + Config::define( 'SUBDOMAIN_INSTALL', false ); + // Use PANTHEON_HOSTNAME if in a Pantheon environment, otherwise use HTTP_HOST. + Config::define( 'DOMAIN_CURRENT_SITE', defined( 'PANTHEON_HOSTNAME' ) ? PANTHEON_HOSTNAME : $_SERVER['HTTP_HOST'] ); + Config::define( 'PATH_CURRENT_SITE', '/' ); + Config::define( 'SITE_ID_CURRENT_SITE', 1 ); + Config::define( 'BLOG_ID_CURRENT_SITE', 1 ); + ``` +6. Save your changes and commit them to your Git repository. WordPress will prompt you to log back in after you push the changes. +7. Log into your site. When you log back into your WordPress admin dashboard, you will see a new **My Sites** menu item in the top left corner. This is where you can manage your network of sites. You now have a WordPress subdirectory multisite network set up on a WordPress (Composer Managed)-based upstream. + ![My Sites](../../../images/wordpress-composer/04-multisite-my-sites.png) + + +Currently, the built-in dashboard [WordPress Multisite Search and Replace](/guides/multisite/search-replace/) does not support Composer-based WordPress multisites. To perform a search and replace on a WordPress (Composer Managed) multisite, you will need to use WP-CLI via Terminus manually. For more information, see our [WordPress Multisite Search and Replace](guides/multisite/workflows/#run-wp-cli-search-replace-manually) guide. + + ## Develop the Multisite Congratulations on setting up your first WordPress Multisite. When you log in to the WordPress Dashboard, you'll see a **My Sites** menu item in the toolbar: @@ -178,8 +214,8 @@ define( 'DOMAIN_CURRENT_SITE', PANTHEON_HOSTNAME ); ## More Resources -- [Environment-Specific Configuration for WordPress Sites](/guides/environment-configuration/environment-specific-config) - -- [WordPress Pantheon Cache Plugin Configuration](/guides/wordpress-configurations/wordpress-cache-plugin) - -- [WordPress with Composer on Pantheon](/guides/wordpress-composer) +* [Environment-Specific Configuration for WordPress Sites](/guides/environment-configuration/environment-specific-config) +* [WordPress Pantheon Cache Plugin Configuration](/guides/wordpress-configurations/wordpress-cache-plugin) +* [WordPress with Composer on Pantheon](/guides/wordpress-composer) +* [WordPress Multisite documentation](https://developer.wordpress.org/advanced-administration/multisite/) +* [WordPress Multisite Domain Mapping](https://developer.wordpress.org/advanced-administration/multisite/domain-mapping/) diff --git a/source/content/guides/wordpress-composer/03-create-wp-site-composer-ci-auto-test.md b/source/content/guides/wordpress-composer/03-create-wp-site-composer-ci-auto-test.md deleted file mode 100644 index 7c94e8882b..0000000000 --- a/source/content/guides/wordpress-composer/03-create-wp-site-composer-ci-auto-test.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -title: WordPress with Composer on Pantheon -subtitle: Create a Composer-managed WordPress Site with Terminus Build Tools -description: Learn how to create a WordPress Site that uses Composer, Continuous Integration, and Automated Testing on Pantheon -contenttype: [guide] -innav: [false] -categories: [dependencies] -cms: [wordpress] -audience: [development] -product: [--] -integration: [--] -tags: [wordpress] -contributors: [whitneymeredith,jazzsequence] -showtoc: true -permalink: docs/guides/wordpress-composer/create-wp-site-composer-ci-auto-test ---- - -This section provides steps to create a new Pantheon WordPress site that will use [Composer](https://getcomposer.org/), Continuous Integration (CI), and Automated Testing. This guide will get you started, but you will need to customize and maintain the CI/testing set up for your projects. - - - -Pantheon has a [WordPress (Composer Managed)](/guides/wordpress-composer/wordpress-composer-managed) upstream. You can use this upstream to create a Composer-managed WordPress site with **Bedrock**. **Terminus Build Tools** does not currently support the Bedrock-based WordPress (Composer Managed) upstream. - - - -## Requirements - -- [Terminus Build Tools Plugin](https://github.com/pantheon-systems/terminus-build-tools-plugin) - - You must use the [Build Tools 3.x release](https://github.com/pantheon-systems/terminus-build-tools-plugin/tree/3.x) if you are using **Terminus 3**. -- [PHP version](/guides/php/php-versions#verify-current-php-versions) 7.2 or greater - -## Create Your Site - -1. Use the [Terminus Build Tools Plugin](https://github.com/pantheon-systems/terminus-build-tools-plugin). - - - The Terminus Build Tools plugin will scaffold the new project, including: - - - A Git repository - - A free [Pantheon sandbox](/guides/legacy-dashboard/create-sites#sandbox-sites) site - - [Continuous Integration](https://pantheon.io/integrations/continuous-integration) configuration - - Credential set up - -1. Run the following command to spin up your site: - - ```bash - terminus build:project:create wp - ``` - - - This site will be based on the Pantheon-maintained [WordPress Composer repository](https://github.com/pantheon-systems/example-wordpress-composer). - - This repository has a similar structure to the [Bedrock-based WordPress (Composer Managed) upstream](https://github.com/pantheon-upstreams/wordpress-composer-managed) but does not use Bedrock. This repository will be deprecated in the future in favor of integrating the Bedrock-based upstream into Build Tools. - -1. Review the sections below for important information about your site, including an explanation of the directory structure, Continuous Integration functions, and essential configuration actions. - -## Review Important Directories and Update File Paths - -### `/web` Directory - -Your site is stored and served from the `/web` subdirectory located next to the `pantheon.yml` file. You must store your website in this subdirectory for a Composer-based workflow. Placing your website in the subdirectory also allows you to store tests, scripts, and other files related to your project in your repo without affecting your web document root. It also provides additional security by preventing web access to files outside of the document root through Pantheon. -Your files may still be accessible from your version control project if it is public. See the [`pantheon.yml` documentation](/pantheon-yml#nested-docroot) for details. - -1. Verify that your website is stored in the `/web` subdirectory. - -### `/web/wp` Directory - -Your directories and files within the `/web` directory are stored in different locations compared to a default WordPress installation. [WordPress allows installing WordPress core in its own directory](https://developer.wordpress.org/advanced-administration/server/wordpress-in-directory/), which is necessary when installing WordPress with Composer. The overall layout of directories in the repo is similar to [Bedrock](https://github.com/roots/bedrock). - -1. Verify that the `WP_SITEURL` file is in the `/web/wp` directory to allow WordPress core functions to work correctly. - -1. Review the `/web/wp-config.php` file for key settings and move other files to the to the `/web/wp` directory as necessary. - -### `composer.json` File - -This project uses Composer to manage third-party PHP dependencies. Some files, such as `web/wp`, may not be visible in the repository. This is because WordPress core and its plugins are installed via Composer and ignored in the `.gitignore` file. - -Third-party WordPress dependencies, such as plugins and themes, are added to the project via `composer.json` file. The `composer.lock` file keeps track of the exact dependency version. Composer installer-paths are used to ensure the WordPress dependencies are downloaded into the appropriate directory. - -Non-WordPress dependencies are downloaded to the `/vendor` directory. - -1. Place all dependencies in the **require** section of your `composer.json` file. - - - This includes dependencies that are only used in non-Live environments. All dependencies in the **require** section are pushed to Pantheon. - -1. Place all dependencies that are not a part of the web application but are necessary to build or test the project in the **require-dev** section. - - - Example dependencies are `php_codesniffer` and `phpunit`. Dev dependencies are deployed to Dev and Multidev environments, but not to Test and Live environments. - -## Continuous Integration - -The scripts that run on Continuous Integration are stored in the `.ci` directory. Provider-specific configuration files, such as `.circle/config.yml` and `.gitlab-ci.yml` use these scripts. - -The scripts are organized into subdirectories according to their function: - -- Build -- Deploy -- Test - -### Build Scripts .ci/build - -- `.ci/build` script builds an artifact suitable for deployment. - -- `.ci/build/php` installs PHP dependencies with Composer. - -### Build Scripts `.ci/deploy` - -All scripts stored in the `.ci/deploy` directory facilitate code deployment to Pantheon. - - - `.ci/deploy/pantheon/create-multidev` creates a new [Pantheon Multidev environment](/guides/multidev) for branches other than the default Git branch. Note that not all users have Multidev access. Please consult the [Multidev FAQ doc](/guides/multidev/multidev-faq) for details. - -- `.ci/deploy/pantheon/dev-multidev` deploys the built artifact to either the Pantheon Dev or a Multidev environment, depending on the Git branch. - -## Automated Test Scripts `.ci/tests` - -The `.ci/tests` scripts run automated tests. You can add or remove scripts depending on your testing needs. - -### Static Testing - -- `.ci/test/static` and `tests/unit` are static tests that analyze code without executing it. These tests are good at detecting syntax errors but not functionality errors. - -- `.ci/test/static/run` runs [PHP CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) with [WordPress coding standards](https://github.com/WordPress/WordPress-Coding-Standards), [PHP Unit](https://phpunit.de/), and [PHP syntax checking](https://phpcodechecker.com/). - -- `tests/unit/bootstrap.php` bootstraps the Composer autoloader. - -- `tests/unit/TestAssert.php` provides an example Unit test. - -1. Create all project-specific test files in the `tests/unit` directory. - -### Visual Regression Testing - -The scripts stored in the `.ci/test/visual-regression` directory run visual regression testing through a headless browser to take screenshots of web pages and compare them for visual differences. - -- `.ci/test/visual-regression/run` runs [BackstopJS](https://github.com/garris/BackstopJS) visual regression testing. - -- `.ci/test/visual-regression/backstopConfig.js` is the [BackstopJS](https://github.com/garris/BackstopJS) configuration file. - -1. Update the settings in `.ci/test/visual-regression/backstopConfig.js` file for your project. - - - For example, the `pathsToTest` variable determines the URLs to test. - -## Behat Testing - -Behat testing uses `.ci/test/behat` and `tests/behat`. [Behat](https://behat.org/en/latest/) is an acceptance/end-to-end testing framework written in PHP. It facilitates testing the fully-built WordPress site on Pantheon. [WordHat](https://github.com/paulgibbs/behat-wordpress-extension) is used to help integrate Behat and WordPress. - -- `.ci/test/behat/initialize` deletes any existing WordPress user from Behat testing and creates a backup of the environment to be tested. - -- `.ci/test/behat/run` sets the `BEHAT_PARAMS` environment variable with dynamic information necessary for Behat and configures it to use [WP-CLI](https://wp-cli.org/) via [Terminus](/terminus). This script also creates the necessary WordPress user, starts headless Chrome, and runs Behat. - -- `.ci/test/behat/cleanup` restores the previously made database backup, deletes the WordPress user created for Behat testing, and saves screenshots taken by Behat. - -- `tests/behat/behat-pantheon.yml` runs tests against the Pantheon site. - -- `tests/behat/tests/behat/features` stores Behat `.feature` extension test files. - -1. Store all `.feature` extension test files in the `tests/behat/tests/behat/features` directory. - - - The example tests must be replaced with project-specific tests. - - - `tests/behat/tests/behat/features/visit-homepage.feature` is a Behat test file that visits the homepage and verifies a `200` response. - - - `tests/behat/tests/behat/features/admin-login.feature` is a Behat test file that logs into the WordPress dashboard as an administrator and verifies access to new user creation. - - - `tests/behat/tests/behat/features/admin-login.feature` is a Behat test file that logs into the WordPress dashboard as an administrator, updates the `blogname` and `blogdescription` settings, clears the Pantheon cache, visits the home page, and verifies how the updated blog name and description appear. - - -## GitHub Actions - -This section provides information enabling GitHub Actions for your site. - -The Build Tools Site will configure GitHub Actions automatically if it was passed as the selected CI when creating the site. You will need to consult advanced external resources if you're working with an existing non-Build Tools site and want to add Github Actions. - -The steps to enable GitHub Actions for an existing Build Tools site created with another CI (for example, CircleCI) shown below might work for you. - -1. Copy `.ci/.github` to `.github`. - -1. Add the following secrets to the Github Actions configuration: - - - `ADMIN_EMAIL` - - - `ADMIN_PASSWORD` - - - `ADMIN_USERNAME` - - - `TERMINUS_TOKEN` - - - `TERMINUS_SITE` - - - `SSH_PRIVATE_KEY` - - - `GH_TOKEN` - - -## Working Locally with Lando - -Complete the one-time steps below to get started using [Lando](https://docs.devwithlando.io/) for local development. Please note than Lando is an independent product and is not supported by Pantheon. Refer to the [Lando documentation](https://docs.devwithlando.io/) for more information. - -1. [Install Lando](https://docs.lando.dev/getting-started/installation.html) if it is not already installed. - -1. Clone your project repository from GitHub to your local. - -1. Manually create a `.lando.yml` file with your preferred configuration, based on the WordPress recipe. - -1. Run `lando start` to start Lando. - -1. Save the local site URL. - - - The local site URL should look similar to: `https://.lndo.site.` - -1. Run the command below to download dependencies. - - ```bash - `lando composer install --no-ansi --no-interaction --optimize-autoloader --no-progress` - ``` - -1. Run the command below to download the media files and database from Pantheon. - - ```bash - `lando pull --code=none` - ``` - -1. Visit the local site URL saved in the preceding steps. - - - You should now be able to edit your site locally. The steps above do not need to be completed on subsequent starts. You can stop Lando with `lando stop` and start it again with `lando start`. - -1. Run all Composer, Terminus and wp-cli commands in Lando instead of the host machine. - - - This is done by prefixing the desired command with `lando`. For example, after a change to `composer.json` run `lando composer update` rather than `composer update`. - - - -Do NOT push/pull code between Lando and Pantheon directly. All code should be pushed to GitHub and deployed to Pantheon through a continuous integration service, such as CircleCI. - - - -## More Resources - -- [Install and Configure Lando for WordPress](/guides/local-development/lando-wordpress) diff --git a/source/content/guides/wordpress-composer/04-multisite-configuration.md b/source/content/guides/wordpress-composer/04-multisite-configuration.md deleted file mode 100644 index bdc95a0349..0000000000 --- a/source/content/guides/wordpress-composer/04-multisite-configuration.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: WordPress with Composer on Pantheon -subtitle: Multisite Configuration -description: Learn how to configure a WordPress multisite with Composer on Pantheon. -contenttype: [guide] -innav: [false] -categories: [dependencies] -cms: [wordpress] -audience: [development] -product: [--] -integration: [--] -tags: [wordpress] -contributors: [jazzsequence] -layout: guide -showtoc: true -permalink: docs/guides/wordpress-composer/multisite-configuration -anchorid: multisite-configuration ---- - -This section provides information on how to configure your WordPress (Composer Managed) site on Pantheon for WordPress multisite. This guide assumes that you have already set up a [WordPress Multisite upstream](/guides/multisite/#request-a-wordpress-multisite) and created a new site using that upstream. If you haven't already, you should also read through our [guide on WordPress Multisite](/guides/multisite) before beginning this process. - -Because Bedrock uses `Config::define()` and `config/application.php` instead of traditional `define()` statements in `wp-config.php`, you will not be able to use WP-CLI via Terminus to enable multisite as documented in our standard [multisite configuration guide](/guides/multisite/config/). - - - -Adjust placeholders in code snippets as needed throughout this guide. This includes placeholders such as `` and `` in Terminus commands, in addition to placeholders in brackets `<>` in larger code blocks. - - - -## Set Up WordPress Multisite - -1. Set the site's connection mode to Git: - - ```bash{promptUser: user} - terminus connection:set .dev git - ``` -2. Open the `config/application.php` file in your site's codebase and add the following line anywhere _above_ the `Config::apply();` line: - - ```php - Config::define( 'WP_ALLOW_MULTISITE', true ); - ``` -3. Visit your development site's WordPress admin and navigate to **Tools** > **Network Setup**. - ![Network Setup page](../../../images/wordpress-composer/04-multisite-network-setup.png) -4. Choose **Sub-domains** or **Sub-directories** (depending on your needs), fill in the Network Title and Admin Email, and click **Install**. -5. You will be given instructions to update your `config/application.php` file. Below where you added the `WP_ALLOW_MULTISITE` line, copy and paste the code provided. The `SUBDOMAIN_INSTALL` value will be `true` or `false` depending on the option you chose in the previous step. For example, if you chose subdirectories, your `config/application.php` file should look like this: - - ```php - Config::define( 'MULTISITE', true ); - Config::define( 'SUBDOMAIN_INSTALL', false ); - // Use PANTHEON_HOSTNAME if in a Pantheon environment, otherwise use HTTP_HOST. - Config::define( 'DOMAIN_CURRENT_SITE', defined( 'PANTHEON_HOSTNAME' ) ? PANTHEON_HOSTNAME : $_SERVER['HTTP_HOST'] ); - Config::define( 'PATH_CURRENT_SITE', '/' ); - Config::define( 'SITE_ID_CURRENT_SITE', 1 ); - Config::define( 'BLOG_ID_CURRENT_SITE', 1 ); - ``` -6. Save your changes and commit them to your Git repository. WordPress will prompt you to log back in after you push the changes. -7. Log into your site. When you log back into your WordPress admin dashboard, you will see a new **My Sites** menu item in the top left corner. This is where you can manage your network of sites. You now have a WordPress subdirectory multisite network set up on a WordPress (Composer Managed)-based upstream. - ![My Sites](../../../images/wordpress-composer/04-multisite-my-sites.png) - -## Using Subdomain Multisite on Pantheon - -Pantheon does not support sub-subdomains on the `pantheonsite.io` platform domain. This means that sub-sites on a subdomain multisite will not be accessible by default. See the [Mapping Custom Hostnames](/guides/multisite/config/#map-custom-hostnames-subdomain-configurations-only) panel in the Multisite Configuration guide for how to set up a custom domain for your sub-sites. - -## Multisite Search and Replace with WordPress (Composer Managed) -Currently, the built-in dashboard [WordPress Multisite Search and Replace](/guides/multisite/search-replace/) does not support Composer-based WordPress multisites. To perform a search and replace on a WordPress (Composer Managed) multisite, you will need to use WP-CLI via Terminus manually. For more information, see our [WordPress Multisite Search and Replace](guides/multisite/workflows/#run-wp-cli-search-replace-manually) guide. - -## More Information - -* [WordPress Multisite Configuration](/guides/multisite/config/) -* [WordPress Multisite Search and Replace](/guides/multisite/search-replace/) -* [WordPress Multisite documentation](https://developer.wordpress.org/advanced-administration/multisite/) -* [WordPress Multisite Domain Mapping](https://developer.wordpress.org/advanced-administration/multisite/domain-mapping/) diff --git a/source/content/guides/wordpress-composer/06-wordpress-ic.md b/source/content/guides/wordpress-composer/06-wordpress-ic.md deleted file mode 100644 index 08d4885780..0000000000 --- a/source/content/guides/wordpress-composer/06-wordpress-ic.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: WordPress with Composer on Pantheon -subtitle: Create a Composer-managed WordPress Site with Integrated Composer and Custom Upstreams -description: Learn how to use Integrated Composer and Custom Upstreams with WordPress on Pantheon. -contenttype: [guide] -innav: [false] -categories: [dependencies] -cms: [wordpress] -audience: [development] -product: [--] -integration: [--] -tags: [wordpress] -contributors: [whitneymeredith,jazzsequence] -showtoc: true -permalink: docs/guides/wordpress-composer/wordpress-ic ---- - -[Integrated Composer](/guides/integrated-composer) is a Pantheon platform feature. Integrated Composer extends Composer functionality to WordPress core files and treats them as a managed dependency. Integrated Composer lets you deploy your site on Pantheon with one-click updates for both upstream commits and Composer dependencies, while still receiving upstream updates. - -## WordPress with Integrated Composer on Pantheon - -Pantheon maintains a [Composer-enabled WordPress Upstream](https://github.com/pantheon-upstreams/wordpress-composer-managed) repository. This is the recommended starting point for forking new upstreams that work with Pantheon's Integrated Composer build process. - -This repository is still under active development. As with all custom upstreams, you are responsible for maintaining your custom upstream and making sure it is up-to-date with the source upstream. There is no guarantee of backwards compatibility. - -Pantheon upstreams influence the Composer packages that are included in downstream sites by including two `composer.json` files in this repository: - -- The root `/composer.json` file is owned by the downstream site. Maintainers of _custom upstreams_ should avoid editing this file. This allows the downstream site maintainer to adjust the `/composer.json` file without creating potential conflicts when merging upstream updates. - -- The `upstream-configuration/composer.json` file is owned by the upstream maintainer. It is included by the root `composer.json` file, and allows upstreams to add or remove packages from downstream sites. Changes are automatically incorporated into the downstream site whenever upstream updates are applied. Pantheon has developed a tool to help you work with upstream configuration called [upstream-management](https://packagist.org/packages/pantheon-systems/upstream-management), which you can install by using `composer require pantheon-systems/upstream-management:^1`. - -## Create Your WordPress Integrated Composer Site - -Follow the steps in this section to create a new WordPress site using Integrated Composer and Upstream. - -1. Fork the [Pantheon-maintained WordPress Upstream repository](https://github.com/pantheon-upstreams/wordpress-composer-managed). - -1. [Connect your repository](/guides/custom-upstream/create-custom-upstream#connect-repository-to-pantheon) to Pantheon. - -1. Update the **require** section of the root `/composer.json` file to match the name you chose in the preceding step. - -## Add and Remove Packages - -1. Use `composer require`in the `upstream-configuration` directory (or `composer upstream-require` if using `upstream-management`) to edit the upstream `composer.json` file. - - The repository template places a theme in the upstream `composer.json` file. This works well for downstream sites that all use the same theme. You should remove themes from the upstream `composer.json` file if you do not intend to use the upstream to lock downstream sites into a particular theme. You cannot remove installed packages from downstream sites if the packages were included from the upstream site. - -## Maintain Your Integrated Composer Fork - - There are some special considerations to keep in mind if you intend to make modifications to your upstream based on this repository. - -1. Increase the version number listed in the `upstream-configuration/composer.json` file each time you make edits. - - Composer checks the contents of the root `/composer.json` file for changes that should be pushed to your upstream configuration. - -1. Verify your changes to the `upstream-configuration/composer.json` file by running `composer install` or `composer update` in the `upstream-configuration` directory. - - Be careful not to rely on ["root-only" properties of composer.json](https://getcomposer.org/doc/04-schema.md). - -## Manage Your WordPress Integrated Composer Site - -1. Review the [Integrated Composer Guide](/guides/integrated-composer) for information on how to: - - [Manage Core as a Project Dependency](/guides/composer#managing-core-as-a-project-dependency) - - [Serve Sites from the Web Subdirectory](/nested-docroot) - - [Add a Dependency to an Individual Site](/guides/integrated-composer#add-a-dependency-to-an-individual-site) - - [Add a Package from a Private Repository](/guides/integrated-composer/private-repo-package) - - [Apply One-click Updates](/guides/integrated-composer/one-click-updates) - - [Add dependencies to your Upstream](/guides/integrated-composer/ic-upstreams) - -1. Review the [Custom Upstreams](/guides/custom-upstream/maintain-custom-upstream) documentation to learn how to: - - [Test and Release Pantheon Core Updates](/guides/custom-upstream/maintain-custom-upstream#test-and-release-pantheon-core-updates) - - [Automatically Resolve Conflicts from the Command Line](/guides/custom-upstream/maintain-custom-upstream#automatically-resolve-from-the-command-line) - - [Tips and Tricks for Maintaining Custom Upstreams](/guides/custom-upstream/maintain-custom-upstream#delete-custom-upstream) - - [Delete a Custom Upstream](/guides/custom-upstream/maintain-custom-upstream#delete-custom-upstream) - -1. Review the [Pantheon YAML Configuration Files](/pantheon-yml) documentation to learn about: - - [Custom Upstream Configurations](/pantheon-yml#custom-upstream-configurations) - -## More Resources - -- [Best Practices for Maintaining Custom Upstreams](/guides/custom-upstream/maintain-custom-upstream) -- [Composer Fundamentals and WebOps Workflows](/guides/composer) -- [Create a Composer-managed WordPress Site with Bedrock](/guides/wordpress-composer/wordpress-composer-managed) diff --git a/source/content/partials/ic-upstream-structure.md b/source/content/partials/ic-upstream-structure.md index 8c4a55384d..b49ead3a3d 100644 --- a/source/content/partials/ic-upstream-structure.md +++ b/source/content/partials/ic-upstream-structure.md @@ -16,18 +16,18 @@ code/ ├─ composer.json └─ pantheon.upstream.yml ├─ README.md -└─ upstream-configuration/ or upstream-config/ for WordPress +└─ upstream-configuration/ └─ composer.json └─ web/ └─ sites/ for Drupal - └─ wp-content/ for WordPress + └─ app/ for WordPress (Composer Managed) (plugins, themes, and uploads) + └─ wp/ for WordPress (Composer Managed) (core files) ``` - `.gitignore`: Prevents [build artifacts](/guides/integrated-composer#build-and-deploy-terminology) generated by Composer from being committed to the upstream or site code repositories. Note that changing the tracking status of Composer-managed files and directories can result in build failures or lead to unexpected errors. - `composer.json`: The two different `composer.json` files allows you to customize individual sites without inherent merge conflicts and enables one-click updates. - Root-level: Site-level customizations. - - Drupal: `upstream-configuration/` or WordPress: `upstream-config/`: - - `composer.json`: Composer automatically updates `composer.json` with customizations for the upstream. Avoid manually modifying this file. + - `upstream-configuration/`: Composer automatically updates `composer.json` with customizations for the upstream. Avoid manually modifying this file. - `pantheon.upstream.yml`: The `build_step: true` directive in `pantheon.upstream.yml` enables the build step. When a site is created, Pantheon runs `composer install`, generates a `composer.lock` file, and commits it back to the site’s code repository. To avoid potential merge conflicts after applying an upstream update, do **not** commit the `composer.lock` file from your upstream root to the upstream repository.