[BUGS-7678] WP config HTTP_HOST documentation updates (#8969)

* update recommended config for HTTP_HOST issue
this matches what we're putting into the mu-plugin

* add undefined array key HTTP_HOST warning as a known issue

* add release note for mu-plugin update

* reset the SUBDOMAIN_INSTALL constant back to what it was before

* update the docs about $_SERVER being/not being available
whether or not the full superglobal is available is somewhat irrelevant, we can just talk about the value we actually care about, which is HTTP_HOST

* clarify language about web/non-web requests

* update docs to remove complicated switch

* also update the complicated switch logic for the gui instructions

* add HTTP_HOST warning info to troublehsooting at the bottom

* detail how to override PANTHEON_HOSTNAME

* re-add WP_ALLOW_MULTISITE to code blocks
was pulled in the purge

* clarify the language a bit

* remove unnecessary extra line and make `wp-config.php` a code block

* update troubleshooting info for HTTP_HOST warnings

* whitespace

* update release note

* add contrib

* update the date

* update code snippet to include fallback to `HTTP_HOST`
if `$_ENV['PANTHEON_ENVIRONMENT']` is unset (e.g. in non-Lando local development environments), using PANTHEON_HOSTNAME will fatal as undefined, so we still need a fallback here.

Author: jazzsequence

source/content/guides/multisite/03-config.md

@@ -68,20 +68,20 @@ Make sure [Terminus](/terminus) is installed and [authenticated](/terminus/insta
 
 1. Open the `code` folder in your SFTP client, and download your site's `wp-config.php` file.
 
-1. Locate the configuration added by WP-CLI, and *modify* the line that sets `DOMAIN_CURRENT_SITE` from a hardcoded URL to a dynamic URL `$_SERVER['HTTP_HOST']`. This automatically detects the URL in each environment. You must replace this variable. For example:
-
+1. Locate the configuration added by WP-CLI, and *modify* the line that sets `DOMAIN_CURRENT_SITE` to a hardcoded URL. We have provided a constant in `wp-config-pantheon.php`, `PANTHEON_HOSTNAME` that defaults to a dynamic URL for web requests (`$_SERVER['HTTP_HOST']`, when available), while providing a fallback for non-web requests (notably workflows like search and replace) that do not have a `$_SERVER['HTTP_HOST']` value.
+  
   ```php:title=wp-config.php
   define( 'WP_ALLOW_MULTISITE', true );
   define( 'MULTISITE', true );
-  define( 'SUBDOMAIN_INSTALL', false ); // Set this to TRUE for Subdomains
-  $base = '/';
-  define( 'DOMAIN_CURRENT_SITE', $_SERVER['HTTP_HOST'] );
+  define( 'SUBDOMAIN_INSTALL', false ); // Set this to TRUE for Subdomain installs.
+  // Use PANTHEON_HOSTNAME if in a Pantheon environment, otherwise use HTTP_HOST.
+  define( 'DOMAIN_CURRENT_SITE', defined( 'PANTHEON_HOSTNAME' ) ? PANTHEON_HOSTNAME : $_SERVER['HTTP_HOST'] );
   define( 'PATH_CURRENT_SITE', '/' );
   define( 'SITE_ID_CURRENT_SITE', 1 );
   define( 'BLOG_ID_CURRENT_SITE', 1 );
   ```
 
-    Refer to the [wp-config-php documentation](/guides/php/wp-config-php#write-logic-based-on-the-pantheon-server-environment) if you have an environment specific configuration.
+  Refer to the [`wp-config.php` documentation](/guides/php/wp-config-php#write-logic-based-on-the-pantheon-server-environment) if you have an environment specific configuration.
 
 1. Save your changes and upload the `wp-config.php` file to Pantheon's **Dev** environment.
 
@@ -120,9 +120,11 @@ Complete the steps below after spinning up a new WPMS site from the correct Cust
 1. Locate the `/* That's all, stop editing! Happy Pressing. */` line, and add the following code above this line to enable the WPMS configuration.
 
   ```php:title=wp-config.php
+  define( 'WP_ALLOW_MULTISITE', true );
   define( 'MULTISITE', true );
   define( 'SUBDOMAIN_INSTALL', false ); // Set this to TRUE for Subdomains
-  define( 'DOMAIN_CURRENT_SITE', $_SERVER['HTTP_HOST'] );
+  // Use PANTHEON_HOSTNAME if in a Pantheon environment, otherwise use HTTP_HOST.
+  define( 'DOMAIN_CURRENT_SITE', defined( 'PANTHEON_HOSTNAME' ) ? PANTHEON_HOSTNAME : $_SERVER['HTTP_HOST'] );
   define( 'PATH_CURRENT_SITE', '/' );
   define( 'SITE_ID_CURRENT_SITE', 1 );
   define( 'BLOG_ID_CURRENT_SITE', 1 );
@@ -164,6 +166,16 @@ After these steps are complete, both sites on the WordPress Multisite should loa
 
 Explore the WordPress Network Dashboard to become familiar with the variety of additional settings. You can review the options that are available for each site you create, manage users across WordPress Multisite, and learn about the network settings. After you explore the WordPress Network Dashboard, learn how to use the WordPress Multisite with the Pantheon Workflow.
 
+## Troubleshooting
+
+### "Undefined index: HTTP_HOST" PHP Warnings
+
+If you see notices in your PHP logs similar to `PHP Warning: Undefined index: HTTP_HOST`, this is likely because there is some code in your configuration that is using `$_SERVER['HTTP_HOST']` without checking if it is set. This is a common issue with WP-CLI, as it does not have the same environment variables set as a web request. Instead of relying on `$_SERVER['HTTP_HOST']`, you can use the `PANTHEON_HOSTNAME` constant, which is set by Pantheon in `wp-config-pantheon.php` and is available in all environments.
+
+```php
+define( 'DOMAIN_CURRENT_SITE', PANTHEON_HOSTNAME );
+```
+
 ## More Resources
 
 - [Environment-Specific Configuration for WordPress Sites](/guides/environment-configuration/environment-specific-config)

source/content/guides/php/04-wp-config-php.md

@@ -10,7 +10,7 @@ audience: [development]
 product: [--]
 integration: [--]
 tags: [wp-config]
-contributors: [masonjames]
+contributors: [masonjames, jazzsequence]
 showtoc: true
 permalink: docs/guides/php/wp-config-php
 ---
@@ -107,6 +107,16 @@ The following example shows how to hard-code your WordPress debug configuration
 
 <Partial file="wp-debugging.md" />
 
+### How can I override the default `PANTHEON_HOSTNAME` value?
+
+In your `wp-config.php`, above the line that requires `wp-config-pantheon.php`, you can set the `PANTHEON_HOSTNAME` constant to the desired value:
+
+```php:title=wp-config.php
+define( 'PANTHEON_HOSTNAME', 'example.com' );
+```
+
+Note that in most cases you shouldn't need to do this. The logic in the [`wp-config-pantheon.php`](https://github.com/pantheon-systems/WordPress/blob/default/wp-config-pantheon.php#L98) covers most instances where you might need a unique hostname. It's recommended that you only change this in very specific cases and your code has conditions to handle those.
+
 ### How can I read the Pantheon environment configuration, like database credentials?
 
 Refer to [Reading the Pantheon Environment Configuration](/guides/environment-configuration/read-environment-config).

source/content/wordpress-known-issues.md

@@ -51,6 +51,20 @@ Pantheon supports designated use cases for [WordPress Multisite](/guides/multisi
 
 It's especially ill-advised to use Multisite to set up many distinct/separate sites — e.g. running different plugins, for different customers — on a single code installation.
 
+## `Undefined array key "HTTP_HOST"` PHP warnings
+
+If you are seeing an error like `PHP Warning:  Undefined array key "HTTP_HOST"` pointing to a WP-CLI file, this is likely because there is some code in your  configuration that is using `$_SERVER['HTTP_HOST']` without checking if it is set. This is a common issue with WP-CLI, as it does not have the same environment variables set as a web request. You can resolve this by checking if the key is set before using it:
+
+```php
+if (isset($_SERVER['HTTP_HOST'])) {
+    // Your code here
+}
+```
+
+The simplest solution is to search your codebase for `$_SERVER['HTTP_HOST']` and add a check for `isset()` before using it. It's generally a good idea to set a fallback value if the key is not set, to prevent unexpected behavior.
+
+If you are seeing this in a WordPress multisite environment, it might be because your `DOMAIN_CURRENT_SITE` value is set to `$_SERVER['HTTP_HOST']` in your `wp-config.php`. You can set this to the `PANTHEON_HOSTNAME` constant provided by Pantheon instead. See the [WordPress Multisite documentation](/guides/multisite/config) for more information.
+
 ## Plugins with Known Issues
 See [WordPress Plugins and Themes with Known Issues](/plugins-known-issues) for a list of WordPress plugins that are not supported and/or require workarounds.
 

source/releasenotes/2024-04-30-wordpress-pantheon-mu-plugin-1-4-1-update.md

@@ -0,0 +1,9 @@
+---
+title: WordPress and Pantheon MU Plugin v1.4.1 update
+published_date: "2024-04-30"
+categories: [wordpress, plugins, action-required]
+---
+
+We have updated the WordPress core upstreams (WordPress and WordPress (Composer Managed)) to provide a new `PANTHEON_HOSTNAME` constant. This value can be helpful when defining `DOMAIN_CURRENT_SITE` on WordPress multisite installations. By default, the `PANTHEON_HOSTNAME` constant is set to the value of the `HTTP_HOST` server variable, which is the hostname of the request. However, when this value is unavailable, the `PANTHEON_HOSTNAME` provides fallback values, thereby avoiding "Undefined index: HTTP_HOST" warnings. For more information, refer to our [WordPress Multisite configuration guide](/guides/multisite/config).
+
+The latest [1.4.1 release](https://github.com/pantheon-systems/pantheon-mu-plugin/releases) of the Pantheon MU Plugin updates the recommended configuration for  WordPress multisite to use the new `PANTHEON_HOSTNAME` constant when defining `DOMAIN_CURRENT_SITE` rather than the previous recommendation -- either `$_SERVER['HTTP_HOST']` or a complicated PHP switch.