Document how to change the domain for a site (Closes: #61)

_posts/2015-10-11-nginx.md

@@ -72,7 +72,7 @@ If there should be any errors `wp-restart-nginx` will warn you about them and re
 
 ### Redirects
 
-Please see our separate documentation page on [Redirects]({{ site.baseurl }}{% post_url 2019-04-08-redirect %}). In most cases it is recommended to do the redirection and HTTP request rewrite logic in WordPress/PHP, which is much more flexible than Nginx. There are no downsides to doing redirects in WordPress/PHP as it is equally fast as soon as the first redirect has been cached.
+Please see our separate documentation page on [Redirects]({{ site.baseurl }}{% post_url 2019-04-08-redirect %}). **In most cases it is recommended to do the redirection and HTTP request rewrite logic in WordPress/PHP**, which is much more flexible than Nginx. There are no downsides to doing redirects in WordPress/PHP as it is equally fast as soon as the first redirect has been cached.
 
 ### Forcing HTTPS
 

_posts/2019-04-08-redirect.md

@@ -13,7 +13,7 @@ In PHP code you can express whatever redirection logic you want without being co
 
 ```php
 <?php
-// Redirect any requests for www.esimerkki.fi or esimerkki.fi to example.com/fi/
+// Redirect any requests for www.example.fi or example.fi to example.com/fi/
 if ( isset($_SERVER['HTTP_HOST']) && strpos($_SERVER['HTTP_HOST'], 'esimerkki.fi') !== false ) {
   header("Location: https://example.com/fi/", true, 301);
   die();
@@ -50,8 +50,57 @@ switch ($_SERVER['HTTP_HOST']) {
     break;
 
   default:
-    header("Location: https://www.happy-or-not.com/en/", true, 301);
+    header("Location: https://www.example.com/en/", true, 301);
+}
+```
+
+## Changing the domain of a site
+
+If a site was using, say, example.com as its domain, and the goal was to rename the entire site to use example.net instead, one would need to:
+
+1) Change all occurrences of example.com to example.net in WordPress settings and contents.
+
+2) Set redirects to ensure all visitors that arrive to the site with the old domain are automatically redirected to the new domain. Redirects should use HTTP code 301 to signal to search engines and other bots that visit the site that the new domain is now the new canonical domain for the site.
+
+### Changing the domain in WordPress settings and contents
+
+This is easiest done on the command-line with [wp-cli](https://developer.wordpress.org/cli/commands/search-replace/):
 
+```
+# Replace all URLs
+wp search-replace --all-tables //example.com //example.net
+# Replace email addresses
+wp search-replace --all-tables @example.com @example.net
+# Verify with a database search there are no occurrences of the old domain
+wp db search example.com
+# Verify with there are no occurrences of the old domain in the site code either
+wp-find-code example.com
+# Purge caches to ensure all content is fresh from the database
+wp-purge-cache
+```
+
+### Redirecting HTTP requests with old domain to new domain
+
+Once the site settings and contents are in order, deploy the redirects:
+
+```
+cat /data/wordpress/htdocs/wp-content/redirects.php
+
+<?php
+// Check that HTTP_HOST is set (so code is not run on wp-cli invocations)
+if ( isset($_SERVER['HTTP_HOST']) && isset($_SERVER['REQUEST_URI']) ) {
+  switch ($_SERVER['HTTP_HOST']) {
+    # Redirect all traffic to the new domain. This custom redirect is needed on
+    # sites where the built-in WordPress canonical domain does not fully work,
+    # e.g. sites with WPML or other odd plugins.
+    #
+    # Use 301 to make redirect permanent and cached
+    # Use 302 for temporary (non-cached) redirects
+    case "example.com":
+    case "www.example.com":
+      header("Location: https://example.net" . $_SERVER['REQUEST_URI'], true, 301);
+      die();
+  }
 }
 ```