feat: improve flush command with clear all docs, fix double-call bug, add success messages

Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>

Author: Copilot

features/manage-cache.feature

@@ -28,3 +28,24 @@ Feature: Generate cache
       """
       Success: The WP Super Cache is enabled.
       """
+
+    When I run `wp super-cache flush`
+    Then STDOUT should contain:
+      """
+      Success: Cache cleared.
+      """
+
+    When I run `wp post create --post_title='Test post' --post_status=publish --porcelain`
+    Then save STDOUT as {POST_ID}
+
+    When I run `wp super-cache flush --post_id={POST_ID}`
+    Then STDOUT should contain:
+      """
+      Success: Post cache cleared.
+      """
+
+    When I try `wp super-cache flush --post_id=invalid`
+    Then STDERR should contain:
+      """
+      Error: This is not a valid post id.
+      """

src/WP_Super_Cache_Command.php

@@ -32,9 +32,29 @@ private function load() {
 	}
 
 	/**
-	 * Clear something from the cache.
+	 * Clears the cache, or a specific post's cache.
 	 *
-	 * @synopsis [--post_id=<post-id>] [--permalink=<permalink>]
+	 * ## OPTIONS
+	 *
+	 * [--post_id=<post-id>]
+	 * : Clear the cache for the post with this ID.
+	 *
+	 * [--permalink=<permalink>]
+	 * : Clear the cache for the post with this permalink.
+	 *
+	 * ## EXAMPLES
+	 *
+	 *     # Clear all cached pages.
+	 *     $ wp super-cache flush
+	 *     Success: Cache cleared.
+	 *
+	 *     # Clear the cache for a specific post by ID.
+	 *     $ wp super-cache flush --post_id=42
+	 *     Success: Post cache cleared.
+	 *
+	 *     # Clear the cache for a specific post by permalink.
+	 *     $ wp super-cache flush --permalink=https://example.com/my-post/
+	 *     Success: Post cache cleared.
 	 *
 	 * @when after_wp_load
 	 */
@@ -44,21 +64,21 @@ public function flush( $args = array(), $assoc_args = array() ) {
 		$this->load();
 
 		if ( isset( $assoc_args['post_id'] ) ) {
-			if ( is_numeric( $assoc_args['post_id'] ) ) {
-				wp_cache_post_change( $assoc_args['post_id'] );
-			} else {
+			if ( ! is_numeric( $assoc_args['post_id'] ) ) {
 				WP_CLI::error( 'This is not a valid post id.' );
 			}
 
 			wp_cache_post_change( $assoc_args['post_id'] );
+			WP_CLI::success( 'Post cache cleared.' );
 		} elseif ( isset( $assoc_args['permalink'] ) ) {
 			$id = url_to_postid( $assoc_args['permalink'] );
 
-			if ( is_numeric( $id ) ) {
-				wp_cache_post_change( $id );
-			} else {
+			if ( ! is_numeric( $id ) ) {
 				WP_CLI::error( 'There is no post with this permalink.' );
 			}
+
+			wp_cache_post_change( $id );
+			WP_CLI::success( 'Post cache cleared.' );
 		} else {
 			wp_cache_clean_cache( $file_prefix, true );
 			WP_CLI::success( 'Cache cleared.' );