Increase number of args supported by wcs_get_subscriptions() (#811)

* Accept and pass arbitrary query args across to WC_Order_Query.

* Add changelog entry.

---------

Co-authored-by: Matt Allan <[email protected]>

Author: barryhughes

changelog.txt

@@ -1,5 +1,8 @@
 *** WooCommerce Subscriptions Core Changelog ***
 
+= 8.2.0 - 2025-xx-xx =
+* Update - Increase the number of args accepted by wcs_get_subscriptions(), to bring about parity with wc_get_orders().
+
 = 8.1.0 - 2025-03-24 =
 * Update - Improved subscription search performance for WP Post stores by removing unnecessary _order_key and _billing_email meta queries.
 * Update - Make it possible to dispatch the Cancelled Subscription email more than once (when initially set to pending-cancellation, and again when it reaches final cancellation).

tests/unit/test-wcs-functions.php

@@ -824,9 +824,16 @@ public function test_1_wcs_get_subscriptions() {
 	}
 
 	/**
-	 * Deals with cases where we're filtering for status
+	 * Deals with cases where we're querying by status.
+	 *
+	 * Status can be specified in two different ways. Traditionally, via the
+	 * 'subscription_status' argument, but 'status' can also be used directly
+	 * since 7.3.0.
+	 *
+	 * @testWith ["subscription_status"]
+	 *           ["status"]
 	 */
-	public function test_2_wcs_get_subscriptions() {
+	public function test_2_wcs_get_subscriptions( string $status_key ) {
 
 		$subscription_1 = WCS_Helper_Subscription::create_subscription(
 			array(
@@ -877,7 +884,7 @@ public function test_2_wcs_get_subscriptions() {
 		);
 
 		// Check for on-hold
-		$subscriptions = wcs_get_subscriptions( array( 'subscription_status' => 'on-hold' ) );
+		$subscriptions = wcs_get_subscriptions( array( $status_key => 'on-hold' ) );
 
 		$this->assertIsArray( $subscriptions );
 		$this->assertEquals( 1, count( $subscriptions ) );
@@ -892,7 +899,7 @@ public function test_2_wcs_get_subscriptions() {
 		unset( $subscriptions );
 
 		// Pending
-		$subscriptions = wcs_get_subscriptions( array( 'subscription_status' => 'pending' ) );
+		$subscriptions = wcs_get_subscriptions( array( $status_key => 'pending' ) );
 
 		$this->assertIsArray( $subscriptions );
 		$this->assertEquals( 2, count( $subscriptions ) );
@@ -907,7 +914,7 @@ public function test_2_wcs_get_subscriptions() {
 		unset( $subscriptions );
 
 		// Switched
-		$subscriptions = wcs_get_subscriptions( array( 'subscription_status' => 'switched' ) );
+		$subscriptions = wcs_get_subscriptions( array( $status_key => 'switched' ) );
 
 		$this->assertIsArray( $subscriptions );
 		$this->assertEquals( 1, count( $subscriptions ) );
@@ -922,7 +929,7 @@ public function test_2_wcs_get_subscriptions() {
 		unset( $subscriptions );
 
 		// Any
-		$subscriptions = wcs_get_subscriptions( array( 'subscription_status' => 'any' ) );
+		$subscriptions = wcs_get_subscriptions( array( $status_key => 'any' ) );
 
 		$this->assertIsArray( $subscriptions );
 		$this->assertEquals( 8, count( $subscriptions ) );
@@ -937,14 +944,14 @@ public function test_2_wcs_get_subscriptions() {
 		unset( $subscriptions );
 
 		// Trash
-		$subscriptions = wcs_get_subscriptions( array( 'subscription_status' => 'trash' ) );
+		$subscriptions = wcs_get_subscriptions( array( $status_key => 'trash' ) );
 
 		$this->assertIsArray( $subscriptions );
 		$this->assertEmpty( $subscriptions );
 		unset( $subscriptions );
 
 		// Active
-		$subscriptions = wcs_get_subscriptions( array( 'subscription_status' => 'active' ) );
+		$subscriptions = wcs_get_subscriptions( array( $status_key => 'active' ) );
 
 		$this->assertIsArray( $subscriptions );
 		$this->assertEquals( 1, count( $subscriptions ) );
@@ -959,7 +966,7 @@ public function test_2_wcs_get_subscriptions() {
 		unset( $subscriptions );
 
 		// Cancelled
-		$subscriptions = wcs_get_subscriptions( array( 'subscription_status' => 'cancelled' ) );
+		$subscriptions = wcs_get_subscriptions( array( $status_key => 'cancelled' ) );
 
 		$this->assertIsArray( $subscriptions );
 		$this->assertEquals( 1, count( $subscriptions ) );
@@ -974,7 +981,7 @@ public function test_2_wcs_get_subscriptions() {
 		unset( $subscriptions );
 
 		// Expired
-		$subscriptions = wcs_get_subscriptions( array( 'subscription_status' => 'expired' ) );
+		$subscriptions = wcs_get_subscriptions( array( $status_key => 'expired' ) );
 
 		$this->assertIsArray( $subscriptions );
 		$this->assertEquals( 1, count( $subscriptions ) );
@@ -989,7 +996,7 @@ public function test_2_wcs_get_subscriptions() {
 		unset( $subscriptions );
 
 		// Pending Cancellation
-		$subscriptions = wcs_get_subscriptions( array( 'subscription_status' => 'pending-cancel' ) );
+		$subscriptions = wcs_get_subscriptions( array( $status_key => 'pending-cancel' ) );
 
 		$this->assertIsArray( $subscriptions );
 		$this->assertEquals( 1, count( $subscriptions ) );
@@ -1006,7 +1013,7 @@ public function test_2_wcs_get_subscriptions() {
 		$is_hpos_enabled = wcs_is_custom_order_tables_usage_enabled();
 
 		// An invalid status
-		$subscriptions = wcs_get_subscriptions( array( 'subscription_status' => 'rubbish' ) );
+		$subscriptions = wcs_get_subscriptions( array( $status_key => 'rubbish' ) );
 
 		if ( $is_hpos_enabled ) {
 			// No subscriptions should match the invalid status.
@@ -1029,7 +1036,7 @@ public function test_2_wcs_get_subscriptions() {
 		unset( $subscriptions );
 
 		// An invalid status is ignored and does not apply as a clause to the query, while the valid status still applies.
-		$subscriptions = wcs_get_subscriptions( array( 'subscription_status' => [ 'rubbish', 'active' ] ) );
+		$subscriptions = wcs_get_subscriptions( array( $status_key => [ 'rubbish', 'active' ] ) );
 
 		$this->assertIsArray( $subscriptions );
 		$this->assertEquals( 1, count( $subscriptions ) );
@@ -1117,6 +1124,52 @@ public function test_5_wcs_get_subscriptions() {
 		$this->assertEquals( $subscriptions, $correct_order );
 	}
 
+	/**
+	 * Since 7.3.0, the number of queries accepted by wcs_get_subscriptions() has broadened,
+	 * and arbitrary arguments can be provided (chiefly to open up access to the features of
+	 * WooCommerce's own order queries).
+	 *
+	 * @return void
+	 */
+	public function test_wcs_get_subscriptions_wc_order_query_compat() {
+		$old_subscription = WCS_Helper_Subscription::create_subscription(
+			array(
+				'status'      => 'pending',
+				'start_date'  => '2024-12-31 00:00:00',
+				'customer_id' => wp_create_user( 'withnail', 'x', '[email protected]' ),
+			)
+		);
+
+		$new_subscription = WCS_Helper_Subscription::create_subscription(
+			array(
+				'status'      => 'pending',
+				'start_date'  => '2025-12-31 00:00:00',
+				'customer_id' => wp_create_user( 'marwood', 'x', '[email protected]' ),
+			)
+		);
+
+		$old_subscription->set_date_created( '2024-12-31 00:00:00' );
+		$new_subscription->set_date_created( '2025-12-31 00:00:00' );
+		$old_subscription->save();
+		$new_subscription->save();
+
+		$old_subscriptions = wcs_get_subscriptions( array( 'date_created' => '<=2025-06-01' ) );
+		$this->assertCount( 1, $old_subscriptions, '`WC_Order_Query` args such as `date_created` can be used when querying for subscriptions.' );
+		$this->assertEquals( $old_subscription->get_id(), current( $old_subscriptions )->get_id(), 'The correct subscription is returned.' );
+
+		// Watch for and capture the query arguments passed to WC_Order_Query.
+		$query_args        = array();
+		$query_arg_watcher = function ( $query, $args ) use ( &$query_args ) {
+			$query_args = $args;
+			return $query;
+		};
+
+		add_filter( 'woocommerce_order_query', $query_arg_watcher, 10, 2 );
+		wcs_get_subscriptions( array( 'foo_bar' => 'baz' ) );
+		$this->assertArrayHasKey( 'foo_bar', $query_args, 'When querying subscriptions, and additional or arbitrary arguments are also passed to `WC_Order_Query`.' );
+		remove_filter( 'woocommerce_order_query', $query_arg_watcher );
+	}
+
 	/**
 	 * Test for non-existent product
 	 */