Add --match-args option to wp cron event delete to target specific event instances (#131)

* Initial plan

* Add --match-args option to wp cron event delete for filtering by event arguments

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

* Apply suggestions from code review

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: swissspidy <841956+swissspidy@users.noreply.github.com>
Co-authored-by: Pascal Birchler <pascalb@google.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 3 people

features/cron.feature

@@ -583,3 +583,68 @@ Feature: Manage WP-Cron events and schedules
       """
       Error: Please either specify cron events, or use --all.
       """
+
+  Scenario: Delete a specific cron event by matching args
+    When I run `wp cron event schedule wp_cli_test_event_5 '+20 minutes' --0=banana`
+    And I run `wp cron event schedule wp_cli_test_event_5 '+20 minutes' --0=bar`
+    Then STDOUT should not be empty
+
+    When I run `wp cron event list --format=csv --fields=hook,recurrence,args`
+    Then STDOUT should be CSV containing:
+      | hook                | recurrence    | args       |
+      | wp_cli_test_event_5 | Non-repeating | ["banana"] |
+      | wp_cli_test_event_5 | Non-repeating | ["bar"]    |
+
+    When I run `wp cron event delete wp_cli_test_event_5 --match-args='["banana"]'`
+    Then STDOUT should be:
+      """
+      Success: Deleted a total of 1 cron event.
+      """
+
+    When I run `wp cron event list --format=csv --fields=hook,args`
+    Then STDOUT should be CSV containing:
+      | hook                | args     |
+      | wp_cli_test_event_5 | ["bar"]  |
+    And STDOUT should not contain:
+      """
+      ["banana"]
+      """
+
+    When I run `wp cron event delete wp_cli_test_event_5 --match-args=bar`
+    Then STDOUT should be:
+      """
+      Success: Deleted a total of 1 cron event.
+      """
+
+    When I try `wp cron event list`
+    Then STDOUT should not contain:
+      """
+      wp_cli_test_event_5
+      """
+
+    When I run `wp cron event schedule wp_cli_test_event_5 '+20 minutes' --0=banana`
+    Then STDOUT should not be empty
+
+    When I try `wp cron event delete wp_cli_test_event_5 --match-args='["banana"]' --all`
+    Then STDERR should be:
+      """
+      Error: The --match-args parameter cannot be combined with --all or --due-now.
+      """
+
+    When I try `wp cron event delete wp_cli_test_event_5 --match-args='["banana"]' --due-now`
+    Then STDERR should be:
+      """
+      Error: The --match-args parameter cannot be combined with --all or --due-now.
+      """
+
+    When I try `wp cron event delete --match-args='["banana"]'`
+    Then STDERR should be:
+      """
+      Error: The --match-args parameter requires exactly one hook name.
+      """
+
+    When I try `wp cron event delete wp_cli_test_event_5 wp_cli_test_event_5 --match-args='["banana"]'`
+    Then STDERR should be:
+      """
+      Error: The --match-args parameter requires exactly one hook name.
+      """

src/Cron_Event_Command.php

@@ -326,19 +326,65 @@ public function unschedule( $args, $assoc_args ) {
 	 * [--all]
 	 * : Delete all hooks.
 	 *
+	 * [--match-args=<args>]
+	 * : Only delete events whose arguments match the given JSON-encoded array or scalar value. Argument types must match exactly (for example, `["123"]` vs `[123]`). Requires exactly one hook name.
+	 *
 	 * ## EXAMPLES
 	 *
 	 *     # Delete all scheduled cron events for the given hook
 	 *     $ wp cron event delete cron_test
 	 *     Success: Deleted a total of 2 cron events.
+	 *
+	 *     # Delete a specific cron event by hook and arguments
+	 *     $ wp cron event delete cron_test --match-args='["123"]'
+	 *     Success: Deleted a total of 1 cron event.
 	 */
 	public function delete( $args, $assoc_args ) {
+		$match_args = Utils\get_flag_value( $assoc_args, 'match-args' );
+
+		if ( null !== $match_args ) {
+			if ( 1 !== count( $args ) ) {
+				WP_CLI::error( 'The --match-args parameter requires exactly one hook name.' );
+			}
+
+			if ( Utils\get_flag_value( $assoc_args, 'all' ) || Utils\get_flag_value( $assoc_args, 'due-now' ) ) {
+				WP_CLI::error( 'The --match-args parameter cannot be combined with --all or --due-now.' );
+			}
+
+			$trimmed_match_args = ltrim( $match_args );
+
+			// Only JSON-decode when the value clearly looks like JSON:
+			// - starts with '[' for arrays
+			// - starts with '"' for explicitly quoted strings
+			if ( '' !== $trimmed_match_args && ( '[' === $trimmed_match_args[0] || '"' === $trimmed_match_args[0] ) ) {
+				$decoded_args = json_decode( $match_args, true );
+				if ( null === $decoded_args && JSON_ERROR_NONE !== json_last_error() ) {
+					// Not valid JSON — treat as a single string argument wrapped in an array.
+					$decoded_args = array( $match_args );
+				} elseif ( ! is_array( $decoded_args ) ) {
+					$decoded_args = array( $decoded_args );
+				}
+			} else {
+				// Treat non-JSON-looking values as a single string argument.
+				$decoded_args = array( $match_args );
+			}
+		}
+
 		$events = self::get_selected_cron_events( $args, $assoc_args );
 
 		if ( is_wp_error( $events ) ) {
 			WP_CLI::error( $events );
 		}
 
+		if ( null !== $match_args ) {
+			$events = array_filter(
+				$events,
+				function ( $event ) use ( $decoded_args ) {
+					return $event->args === $decoded_args;
+				}
+			);
+		}
+
 		$deleted = 0;
 		foreach ( $events as $event ) {
 			$result = self::delete_event( $event );