Fix/issue WOOTAX-298 - Prevent StoreApi fatal on sites running old WooCommerce (#2971)

* Fix StoreApi fatal on old WooCommerce by adding class_exists guard

* add changelog

* Defer Store API extension to woocommerce_blocks_loaded

Register the Store API extension on the woocommerce_blocks_loaded action
instead of guarding extend_store_api() with a per-request class_exists()
check. On WooCommerce versions too old to ship the Store API that action
never fires, so the extension is skipped structurally rather than caught,
and the class_exists() check is removed. When Blocks have already loaded
the extension is registered inline as before.

Add unit tests covering both the deferred and already-loaded paths.

* Register Store API extension on woocommerce_blocks_loaded with class guard

Register extend_store_api() on woocommerce_blocks_loaded, the same hook
the block integration already uses, instead of calling it during
woocommerce_init. The extension only surfaces notices in the block
cart/checkout, and on a WooCommerce too old to ship Blocks the hook never
fires, so nothing runs.

Keep a class_exists() guard on the top-level
Automattic\WooCommerce\StoreApi\StoreApi class inside the callback. That
covers the in-between versions that ship Blocks (so they fire the hook)
but predate that class, which would otherwise still fatal with "Class not
found". When the class is absent the method logs a notice and returns.

Replace the two deferral tests with tests that exercise the guard itself:
registration runs when the class is present, is skipped when it is
absent, and is_store_api_available() tracks the real class.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix: throttle StoreApi-unavailable notice to once per day

extend_store_api() runs on woocommerce_blocks_loaded, which fires on nearly every request. On installs missing the StoreApi class the unavailable notice was written on every page load. Move the logging into log_store_api_unavailable() and gate it behind a daily transient so an affected site logs at most once per day.

Also strengthen the tests: value-pin is_store_api_available() to true in the harness so a class-string typo fails, and add a test asserting the notice fires once and is throttled on the second same-day call.

---------

Co-authored-by: Abdalsalaam Halawa <abdalsalaamnafez@gmail.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Dustin Parker <11618203+dustinparker@users.noreply.github.com>

Author: 4 people

changelog.txt

@@ -1,5 +1,8 @@
 *** WooCommerce Tax Changelog ***
 
+= 3.6.8 - 2026-xx-xx =
+* Fix   - Prevent fatal error on sites running WooCommerce versions without StoreApi support.
+
 = 3.6.7 - 2026-07-06 =
 * Fix   - Prevent fatal error on Atomic sites caused by incorrect path resolution when loading the API client class.
 

readme.txt

@@ -70,6 +70,9 @@ This plugin relies on the following external services:
 
 == Changelog ==
 
+= 3.6.8 - 2026-xx-xx =
+* Fix   - Prevent fatal error on sites running WooCommerce versions without StoreApi support.
+
 = 3.6.7 - 2026-07-06 =
 * Fix   - Prevent fatal error on Atomic sites caused by incorrect path resolution when loading the API client class.
 

tests/php/test-woocommerce-connect-client.php

@@ -247,4 +247,114 @@ public function test_shipping_zone_method_added() {
 		$this->assertEquals( 2, did_action( 'wc_connect_shipping_zone_method_added' ) );
 	}
 
+	/**
+	 * When the StoreApi class is present, extend_store_api() registers the
+	 * plugin's Store API extensions.
+	 *
+	 * @covers WC_Connect_Loader::extend_store_api
+	 */
+	public function test_extend_store_api_registers_when_store_api_available() {
+		$sut = $this->getMockBuilder( 'WC_Connect_Loader' )
+			->disableOriginalConstructor()
+			->setMethods( array( 'is_store_api_available', 'register_store_api_extensions' ) )
+			->getMock();
+
+		$sut->method( 'is_store_api_available' )->willReturn( true );
+		$sut->expects( $this->once() )->method( 'register_store_api_extensions' );
+
+		$sut->extend_store_api();
+	}
+
+	/**
+	 * On WooCommerce versions without the StoreApi class, extend_store_api()
+	 * skips registration instead of fataling on the missing class. This is the
+	 * guard that prevents the `Class "…\StoreApi" not found` fatal (WOOTAX-298).
+	 *
+	 * @covers WC_Connect_Loader::extend_store_api
+	 */
+	public function test_extend_store_api_skips_registration_when_store_api_unavailable() {
+		$sut = $this->getMockBuilder( 'WC_Connect_Loader' )
+			->disableOriginalConstructor()
+			->setMethods( array( 'is_store_api_available', 'register_store_api_extensions' ) )
+			->getMock();
+
+		$sut->method( 'is_store_api_available' )->willReturn( false );
+		$sut->expects( $this->never() )->method( 'register_store_api_extensions' );
+
+		// Must not throw when the StoreApi class is absent.
+		$this->assertNull( $sut->extend_store_api() );
+	}
+
+	/**
+	 * is_store_api_available() returns true when the StoreApi class the plugin
+	 * depends on is present. The PHPUnit harness loads WooCommerce, so the class
+	 * exists here - pinning to true means a typo or rename in the guarded class
+	 * string would fail this test rather than silently tracking the change.
+	 *
+	 * @covers WC_Connect_Loader::is_store_api_available
+	 */
+	public function test_is_store_api_available_returns_true_when_store_api_class_present() {
+		// Precondition: the harness must actually load the StoreApi class for the
+		// assertion below to be meaningful.
+		$this->assertTrue(
+			class_exists( '\Automattic\WooCommerce\StoreApi\StoreApi' ),
+			'Test precondition: the StoreApi class must be loaded in the test harness.'
+		);
+
+		$sut = $this->getMockBuilder( 'WC_Connect_Loader' )
+			->disableOriginalConstructor()
+			->setMethods( null )
+			->getMock();
+
+		$method = new ReflectionMethod( 'WC_Connect_Loader', 'is_store_api_available' );
+		$method->setAccessible( true );
+
+		$this->assertTrue(
+			$method->invoke( $sut ),
+			'is_store_api_available() should return true when the StoreApi class is present.'
+		);
+	}
+
+	/**
+	 * On the unavailable path, extend_store_api() logs a notice - but at most
+	 * once per day, because it runs on `woocommerce_blocks_loaded` (nearly every
+	 * request). The throttle transient must suppress the second same-day call.
+	 *
+	 * @covers WC_Connect_Loader::extend_store_api
+	 * @covers WC_Connect_Loader::log_store_api_unavailable
+	 */
+	public function test_extend_store_api_logs_unavailable_notice_once_per_day() {
+		delete_transient( 'wcservices_store_api_unavailable_logged' );
+
+		// Spy logger injected via the woocommerce_logging_class filter. Returning
+		// an object bypasses wc_get_logger()'s static cache.
+		$logger = $this->getMockBuilder( 'WC_Logger_Interface' )->getMock();
+		$logger->expects( $this->once() )
+			->method( 'notice' )
+			->with(
+				'StoreApi class not found. Store API extensions will not be registered.',
+				array( 'source' => 'woocommerce-services' )
+			);
+
+		$inject_logger = function () use ( $logger ) {
+			return $logger;
+		};
+		add_filter( 'woocommerce_logging_class', $inject_logger );
+
+		$sut = $this->getMockBuilder( 'WC_Connect_Loader' )
+			->disableOriginalConstructor()
+			->setMethods( array( 'is_store_api_available', 'register_store_api_extensions' ) )
+			->getMock();
+
+		$sut->method( 'is_store_api_available' )->willReturn( false );
+		$sut->expects( $this->never() )->method( 'register_store_api_extensions' );
+
+		// First skip logs the notice; the second same-day skip is throttled.
+		$sut->extend_store_api();
+		$sut->extend_store_api();
+
+		remove_filter( 'woocommerce_logging_class', $inject_logger );
+		delete_transient( 'wcservices_store_api_unavailable_logged' );
+	}
+
 }

woocommerce-services.php

@@ -702,6 +702,7 @@ function () {
 			}
 
 			add_action( 'woocommerce_blocks_loaded', array( $this, 'register_blocks_integration' ) );
+			add_action( 'woocommerce_blocks_loaded', array( $this, 'extend_store_api' ) );
 			add_action( 'before_woocommerce_init', array( $this, 'pre_wc_init' ) );
 		}
 
@@ -817,7 +818,6 @@ public function after_wc_init() {
 			$this->service_settings_store->migrate_legacy_services();
 			$this->attach_hooks();
 			$this->init_store_notices();
-			$this->extend_store_api();
 		}
 
 		/**
@@ -976,9 +976,63 @@ public function init_store_notices() {
 		}
 
 		/**
-		 * Extend the Store API.
+		 * Extend the Store API when it is available.
+		 *
+		 * Registered on `woocommerce_blocks_loaded` - the same hook the block
+		 * integration uses - because the Store API only exists once Blocks load and
+		 * our extension only surfaces notices in the block cart/checkout. On a
+		 * WooCommerce too old to ship Blocks the hook never fires, so nothing runs.
+		 *
+		 * The `class_exists()` guard covers the in-between case: WooCommerce versions
+		 * that ship Blocks (firing this hook) but predate the top-level
+		 * `Automattic\WooCommerce\StoreApi\StoreApi` class this plugin depends on.
+		 * Without the guard those versions would still fatal with `Class not found`.
 		 */
 		public function extend_store_api() {
+			if ( ! $this->is_store_api_available() ) {
+				$this->log_store_api_unavailable();
+				return;
+			}
+
+			$this->register_store_api_extensions();
+		}
+
+		/**
+		 * Whether the WooCommerce Store API is available on this installation.
+		 *
+		 * @return bool
+		 */
+		protected function is_store_api_available() {
+			return class_exists( '\Automattic\WooCommerce\StoreApi\StoreApi' );
+		}
+
+		/**
+		 * Log, at most once per day, that the Store API is unavailable.
+		 *
+		 * `extend_store_api()` runs on `woocommerce_blocks_loaded`, which fires on
+		 * nearly every request. On installs missing the StoreApi class the notice
+		 * would otherwise be written on every page load, so it is throttled to once
+		 * per day via a transient.
+		 */
+		protected function log_store_api_unavailable() {
+			$transient_key = 'wcservices_store_api_unavailable_logged';
+
+			if ( get_transient( $transient_key ) ) {
+				return;
+			}
+
+			wc_get_logger()->notice(
+				'StoreApi class not found. Store API extensions will not be registered.',
+				array( 'source' => 'woocommerce-services' )
+			);
+
+			set_transient( $transient_key, 1, DAY_IN_SECONDS );
+		}
+
+		/**
+		 * Register the plugin's Store API extensions.
+		 */
+		protected function register_store_api_extensions() {
 			$store_api_extend_schema        = StoreApiExtendSchema::instance();
 			$store_api_extension_controller = new StoreApiExtensionController( $store_api_extend_schema );