From ff48d8d75a1d570aceb996024a87e3f128b176cb Mon Sep 17 00:00:00 2001 From: Chris Reynolds Date: Tue, 15 Oct 2024 10:51:37 -0600 Subject: [PATCH 1/3] delete the multisite config guide under wordpress-composer --- .../04-multisite-configuration.md | 72 ------------------- 1 file changed, 72 deletions(-) delete mode 100644 source/content/guides/wordpress-composer/04-multisite-configuration.md 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/) From 4583484756244067b25a1f128eb3f5785160fd0e Mon Sep 17 00:00:00 2001 From: Chris Reynolds Date: Tue, 15 Oct 2024 10:51:54 -0600 Subject: [PATCH 2/3] add relevant info from the wpcm multisite config to the main multisite config guide --- source/content/guides/multisite/03-config.md | 46 +++++++++++++++++--- 1 file changed, 41 insertions(+), 5 deletions(-) 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/) From 79b7294a99079eacd1b5d2c794e1b337cd105c39 Mon Sep 17 00:00:00 2001 From: Chris Reynolds Date: Tue, 15 Oct 2024 12:02:09 -0600 Subject: [PATCH 3/3] [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 --- .../integrated-composer/06-ic-upstreams.md | 37 +++++++-- .../wordpress-composer/06-wordpress-ic.md | 80 ------------------- .../content/partials/ic-upstream-structure.md | 8 +- 3 files changed, 35 insertions(+), 90 deletions(-) delete mode 100644 source/content/guides/wordpress-composer/06-wordpress-ic.md diff --git a/source/content/guides/integrated-composer/06-ic-upstreams.md b/source/content/guides/integrated-composer/06-ic-upstreams.md index 974ba2b0d8..8657828dff 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: Use an Upstream with Integrated Composer 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 information on how to use an Upstream with Integrated Comp ## 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. ### 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/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.