[CMS-799] Deprecate pantheon-cache command (#2)

* whitespace changes

* add a cli.php file
for all the wp-cli commands

* move the set-maintenance-mode command to cli.php
and rename to pantheon set-maintenance-mode rather than pantheon-cache set-maintenance-mode

* support but deprecate the old pantheon-cache command(s)

* move the maintenance mode function to cli.php
make sure all the wp-cli stuff is in one place

* update the docblock
so running `wp pantheon-cache --help` returns information about the updated command.

* throw a warning rather than an error if the old command is used

* update the docblock so the help function still works

* fix the replacement command
let the replacement command pass the parameter that was used

* update the warning message
warn about the full command and add a splash of color

* add an error condition
if the replacement command is false for some reason display an error. wp-cli should fail internally before we get to this point.

* set the command back to the set-maintenance-mode subcommand

* set the updated command to pantheon cache rather than just pantheon

* document that pantheon-cache will be removed in the future

* update the suggested usage

* add alias for set-maintenance-mode command
allow users to use pantheon set-maintenance-mode rather than only pantheon cache set-maintenance-mode

inc/cli.php

@@ -0,0 +1,96 @@
+<?php
+/**
+ * WP-CLI commands for the Pantheon mu-plugin.
+ *
+ * @package pantheon
+ */
+
+namespace Pantheon\CLI;
+
+use Pantheon_Cache;
+use WP_CLI;
+
+// Support the old pantheon-cache command but return a deprecation notice.
+WP_CLI::add_command( 'pantheon-cache set-maintenance-mode', '\\Pantheon\\CLI\\__deprecated_maintenance_mode_output' );
+WP_CLI::add_command( 'pantheon cache set-maintenance-mode', '\\Pantheon\\CLI\\set_maintenance_mode_command' );
+WP_CLI::add_command( 'pantheon set-maintenance-mode', '\\Pantheon\\CLI\\set_maintenance_mode_command' );
+
+/**
+ * Sets maintenance mode status.
+ *
+ * Enable maintenance mode to work on your site while serving cached pages
+ * to visitors and bots, or everyone except administators.
+ *
+ * ## DEPRECATION NOTICE
+ *
+ * This command is deprecated and will be removed in a future release.
+ * Use `pantheon set-maintenance-mode` instead.
+ *
+ * ## USAGE
+ *
+ * wp pantheon-cache set-maintenance-mode <status> (deprecated) or
+ * wp pantheon cache set-maintenance-mode <status>
+ *
+ * ## OPTIONS
+ *
+ * <status>
+ * : Maintenance mode status.
+ * ---
+ * options:
+ *   - disabled
+ *   - anonymous
+ *   - everyone
+ * ---
+ *
+ * @subcommand set-maintenance-mode
+ *
+ * @deprecated 1.0.0
+ */
+function __deprecated_maintenance_mode_output( $args ) {
+	$allowed_args = [ 'disabled', 'anonymous', 'everyone' ];
+	$replacement_command = ( ! empty( $args  && count( $args ) === 1 ) && in_array( $args[0], $allowed_args, true ) ) ? 'set-maintenance-mode ' . $args[0] : false;
+
+	WP_CLI::warning( WP_CLI::colorize( '%y' . sprintf( __( 'This command is deprecated and will be removed in a future release. Use `wp pantheon %s` instead.', 'pantheon-systems' ), $replacement_command ) . '%n' ) );
+	WP_CLI::line( __( 'Run `wp pantheon set-maintenance-mode --help` for more information.', 'pantheon-systems' ) );
+
+	// The command should fail before we get here, but in case it doesn't, display an error.
+	if ( false === $replacement_command ) {
+		WP_CLI::error( __( 'Invalid arguments. Run `wp pantheon set-maintenance-mode --help` for more infomation.', 'pantheon-systems' ) );
+	}
+
+	set_maintenance_mode_command( $args );
+}
+
+/**
+ * Sets maintenance mode status.
+ *
+ * Enable maintenance mode to work on your site while serving cached pages
+ * to visitors and bots, or everyone except administators.
+ *
+ * ## OPTIONS
+ *
+ * <status>
+ * : Maintenance mode status.
+ * ---
+ * options:
+ *   - disabled
+ *   - anonymous
+ *   - everyone
+ * ---
+ *
+ * @subcommand set-maintenance-mode
+ */
+function set_maintenance_mode_command( $args ) {
+
+	list( $status ) = $args;
+
+	$out = Pantheon_Cache()->default_options;
+	if ( ! empty( $status )
+		&& in_array( $status, [ 'anonymous', 'everyone' ], true ) ) {
+		$out['maintenance_mode'] = $status;
+	} else {
+		$out['maintenance_mode'] = 'disabled';
+	}
+	update_option( Pantheon_Cache::SLUG, $out );
+	WP_CLI::success( sprintf( 'Maintenance mode set to: %s', $out['maintenance_mode'] ) );
+}

inc/pantheon-page-cache.php

@@ -498,40 +498,6 @@ public function cache_clean_urls() {
 			pantheon_clear_edge_paths( $this->paths );
 		}
 	}
-
-	/**
-	 * Sets maintenance mode status.
-	 *
-	 * Enable maintenance mode to work on your site while serving cached pages
-	 * to visitors and bots, or everyone except administators.
-	 *
-	 * ## OPTIONS
-	 *
-	 * <status>
-	 * : Maintenance mode status.
-	 * ---
-	 * options:
-	 *   - disabled
-	 *   - anonymous
-	 *   - everyone
-	 * ---
-	 *
-	 * @subcommand set-maintenance-mode
-	 */
-	public function set_maintenance_mode_command( $args ) {
-
-		list( $status ) = $args;
-
-		$out = $this->default_options;
-		if ( ! empty( $status )
-			&& in_array( $status, [ 'anonymous', 'everyone' ], true ) ) {
-			$out['maintenance_mode'] = $status;
-		} else {
-			$out['maintenance_mode'] = 'disabled';
-		}
-		update_option( self::SLUG, $out );
-		WP_CLI::success( sprintf( 'Maintenance mode set to: %s', $out['maintenance_mode'] ) );
-	}
 }
 
 
@@ -548,11 +514,6 @@ function Pantheon_Cache() {
 }
 add_action( 'plugins_loaded', 'Pantheon_Cache' );
 
-
-if ( defined( 'WP_CLI' ) && WP_CLI ) {
-	WP_CLI::add_command( 'pantheon-cache set-maintenance-mode', [ Pantheon_Cache::instance(), 'set_maintenance_mode_command' ] );
-}
-
 /**
  * @see Pantheon_Cache::clean_post_cache
  *

pantheon.php

@@ -22,14 +22,17 @@
 	if ( 'dev' === $_ENV['PANTHEON_ENVIRONMENT'] && function_exists( 'wp_is_writable' ) ) {
 		require_once 'inc/pantheon-plugin-install-notice.php';
 	}
+    if ( defined( 'WP_CLI' ) && WP_CLI ) {
+        require_once 'inc/cli.php';
+    }
 	if ( ! defined( 'FS_METHOD' ) ) {
 		/**
-		 * When this constant is not set, WordPress writes and then deletes a 
+		 * When this constant is not set, WordPress writes and then deletes a
 		 * temporary file to determine if it has direct access to the filesystem,
-		 * which we already know to be the case.  This multiplies filesystem 
+		 * which we already know to be the case.  This multiplies filesystem
 		 * operations and can degrade performance of the filesystem as a whole in
-		 * the case of large sites that do a lot of filesystem operations.  
-		 * Setting this constant to 'direct' tells WordPress to assume it has 
+		 * the case of large sites that do a lot of filesystem operations.
+		 * Setting this constant to 'direct' tells WordPress to assume it has
 		 * direct access and skip creating the extra temporary file.
 		 */
 		define( 'FS_METHOD', 'direct' );