fix: add wp_supports_ai() and related constant + filter

src/wp-includes/ai-client.php

@@ -9,6 +9,29 @@
 
 use WordPress\AiClient\AiClient;
 
+/**
+ * Returns whether AI features are supported in the current environment.
+ *
+ * @since 7.0.0
+ *
+ * @return bool Whether AI features are supported.
+ */
+function wp_supports_ai(): bool {
+	// Constant check gives a hard short-circuit for environments that cannot be overridden with a filter, such as wp-config.php settings or hosting provider configurations.
+	if ( defined( 'WP_AI_SUPPORT' ) && ! WP_AI_SUPPORT ) {
+		return false;
+	}
+
+	/**
+	 * Filters whether the current request should use AI.
+	 *
+	 * @since 7.0.0
+	 *
+	 * @param bool $is_enabled Whether the current request should use AI. Default true.
+	 */
+	return (bool) apply_filters( 'wp_supports_ai', true );
+}
+
 /**
  * Creates a new AI prompt builder using the default provider registry.
  *

src/wp-includes/ai-client/class-wp-ai-client-prompt-builder.php

@@ -41,6 +41,8 @@
  *
  * @since 7.0.0
  *
+ * @phpstan-import-type Prompt from PromptBuilder
+ *
  * @method self with_text(string $text) Adds text to the current message.
  * @method self with_file($file, ?string $mimeType = null) Adds a file to the current message.
  * @method self with_function_response(FunctionResponse $functionResponse) Adds a function response to the current message.
@@ -165,17 +167,22 @@ class WP_AI_Client_Prompt_Builder {
 	 *
 	 * @since 7.0.0
 	 *
-	 * @param ProviderRegistry                                                                 $registry The provider registry for finding suitable models.
-	 * @param string|MessagePart|Message|array|list<string|MessagePart|array>|list<Message>|null $prompt   Optional. Initial prompt content.
-	 *                                                                                                    A string for simple text prompts,
-	 *                                                                                                    a MessagePart or Message object for
-	 *                                                                                                    structured content, an array for a
-	 *                                                                                                    message array shape, or a list of
-	 *                                                                                                    parts or messages for multi-turn
-	 *                                                                                                    conversations. Default null.
+	 * @param ProviderRegistry $registry The provider registry for finding suitable models.
+	 * @param Prompt           $prompt   Optional. Initial prompt content.
+	 *                                   A string for simple text prompts,
+	 *                                   a MessagePart or Message object for
+	 *                                   structured content, an array for a
+	 *                                   message array shape, or a list of
+	 *                                   parts or messages for multi-turn
+	 *                                   conversations. Default null.
 	 */
 	public function __construct( ProviderRegistry $registry, $prompt = null ) {
 		try {
+			if ( ! wp_supports_ai() ) {
+				// The catch block will convert this to a WP_Error.
+				throw new \RuntimeException( __( 'AI features are not supported in this environment.' ) );
+			}
+
 			$this->builder = new PromptBuilder( $registry, $prompt );
 		} catch ( Exception $e ) {
 			$this->builder = new PromptBuilder( $registry );
@@ -385,7 +392,8 @@ private static function is_generating_method( string $name ): bool {
 	protected function get_builder_callable( string $name ): callable {
 		$camel_case_name = $this->snake_to_camel_case( $name );
 
-		if ( ! is_callable( array( $this->builder, $camel_case_name ) ) ) {
+		$method = array( $this->builder, $camel_case_name );
+		if ( ! is_callable( $method ) ) {
 			throw new BadMethodCallException(
 				sprintf(
 					/* translators: 1: Method name. 2: Class name. */
@@ -396,7 +404,7 @@ protected function get_builder_callable( string $name ): callable {
 			);
 		}
 
-		return array( $this->builder, $camel_case_name );
+		return $method;
 	}
 
 	/**

src/wp-includes/class-wp-connector-registry.php

@@ -168,6 +168,11 @@ public function register( string $id, array $args ): ?array {
 			return null;
 		}
 
+		if ( 'ai_provider' === $args['type'] && ! wp_supports_ai() ) {
+			// No need for a `doing_it_wrong` as AI support is disabled intentionally.
+			return null;
+		}
+
 		$connector = array(
 			'name'           => $args['name'],
 			'description'    => isset( $args['description'] ) && is_string( $args['description'] ) ? $args['description'] : '',

src/wp-includes/connectors.php

@@ -332,6 +332,53 @@ function _wp_connectors_resolve_ai_provider_logo_url( string $path ): ?string {
 function _wp_connectors_init(): void {
 	$registry = new WP_Connector_Registry();
 	WP_Connector_Registry::set_instance( $registry );
+
+	// Only register default AI providers if AI support is enabled.
+	if ( wp_supports_ai() ) {
+		_wp_connectors_register_default_ai_providers( $registry );
+	}
+
+	/**
+	 * Fires when the connector registry is ready for plugins to register connectors.
+	 *
+	 * Built-in connectors and any AI providers auto-discovered from the WP AI Client
+	 * registry have already been registered at this point and cannot be unhooked.
+	 *
+	 * AI provider plugins that register with the WP AI Client do not need to use
+	 * this action — their connectors are created automatically. This action is
+	 * primarily for registering non-AI-provider connectors or overriding metadata
+	 * on existing connectors.
+	 *
+	 * Use `$registry->register()` within this action to add new connectors.
+	 * To override an existing connector, unregister it first, then re-register
+	 * with updated data.
+	 *
+	 * Example — overriding metadata on an auto-discovered connector:
+	 *
+	 *     add_action( 'wp_connectors_init', function ( WP_Connector_Registry $registry ) {
+	 *         if ( $registry->is_registered( 'openai' ) ) {
+	 *             $connector = $registry->unregister( 'openai' );
+	 *             $connector['description'] = __( 'Custom description for OpenAI.', 'my-plugin' );
+	 *             $registry->register( 'openai', $connector );
+	 *         }
+	 *     } );
+	 *
+	 * @since 7.0.0
+	 *
+	 * @param WP_Connector_Registry $registry Connector registry instance.
+	 */
+	do_action( 'wp_connectors_init', $registry );
+}
+
+/**
+ * Registers connectors for the built-in AI providers.
+ *
+ * @since 7.0.0
+ * @access private
+ *
+ * @param WP_Connector_Registry $registry The connector registry instance.
+ */
+function _wp_connectors_register_default_ai_providers( WP_Connector_Registry $registry ): void {
 	// Built-in connectors.
 	$defaults = array(
 		'anthropic' => array(
@@ -430,37 +477,6 @@ function _wp_connectors_init(): void {
 	foreach ( $defaults as $id => $args ) {
 		$registry->register( $id, $args );
 	}
-
-	/**
-	 * Fires when the connector registry is ready for plugins to register connectors.
-	 *
-	 * Built-in connectors and any AI providers auto-discovered from the WP AI Client
-	 * registry have already been registered at this point and cannot be unhooked.
-	 *
-	 * AI provider plugins that register with the WP AI Client do not need to use
-	 * this action — their connectors are created automatically. This action is
-	 * primarily for registering non-AI-provider connectors or overriding metadata
-	 * on existing connectors.
-	 *
-	 * Use `$registry->register()` within this action to add new connectors.
-	 * To override an existing connector, unregister it first, then re-register
-	 * with updated data.
-	 *
-	 * Example — overriding metadata on an auto-discovered connector:
-	 *
-	 *     add_action( 'wp_connectors_init', function ( WP_Connector_Registry $registry ) {
-	 *         if ( $registry->is_registered( 'openai' ) ) {
-	 *             $connector = $registry->unregister( 'openai' );
-	 *             $connector['description'] = __( 'Custom description for OpenAI.', 'my-plugin' );
-	 *             $registry->register( 'openai', $connector );
-	 *         }
-	 *     } );
-	 *
-	 * @since 7.0.0
-	 *
-	 * @param WP_Connector_Registry $registry Connector registry instance.
-	 */
-	do_action( 'wp_connectors_init', $registry );
 }
 
 /**

tests/phpunit/tests/ai-client/wpAiClientPrompt.php

@@ -30,4 +30,25 @@ public function test_returns_independent_instances() {
 
 		$this->assertNotSame( $builder1, $builder2 );
 	}
+
+	/**
+	 * Tests that returns a WP_AI_Client_Prompt_Builder instance even when AI is not supported, but that the builder contains an error.
+	 */
+	public function test_returns_error_builder_when_ai_not_supported(): void {
+		// Temporarily disable AI support for this test.
+		add_filter( 'wp_supports_ai', '__return_false' );
+		$builder = wp_ai_client_prompt();
+		$this->assertInstanceOf( WP_AI_Client_Prompt_Builder::class, $builder );
+
+		// Check the $error prop is a real WP_Error with the expected message.
+		$reflection = new ReflectionClass( $builder );
+		$error_prop = $reflection->getProperty( 'error' );
+		if ( PHP_VERSION_ID < 80100 ) {
+			$error_prop->setAccessible( true );
+		}
+		$error = $error_prop->getValue( $builder );
+
+		$this->assertInstanceOf( WP_Error::class, $error );
+		$this->assertSame( 'AI features are not supported in this environment.', $error->get_error_message() );
+	}
 }

tests/phpunit/tests/ai-client/wpAiClientPromptBuilder.php

@@ -2395,6 +2395,19 @@ public function test_using_ability_method_chaining() {
 		$this->assertEquals( 500, $config->getMaxTokens() );
 	}
 
+	/**
+	 * Tests that is_supported returns false when prevent prompt filter returns true.
+	 *
+	 * @ticket 64591
+	 */
+	public function test_is_supported_returns_false_when_ai_not_supported() {
+		add_filter( 'wp_supports_ai', '__return_false' );
+
+		$builder = new WP_AI_Client_Prompt_Builder( AiClient::defaultRegistry(), 'Test prompt' );
+
+		$this->assertFalse( $builder->is_supported() );
+	}
+
 	/**
 	 * Tests that is_supported returns false when prevent prompt filter returns true.
 	 *
@@ -2407,7 +2420,6 @@ public function test_is_supported_returns_false_when_filter_prevents_prompt() {
 
 		$this->assertFalse( $builder->is_supported() );
 	}
-
 	/**
 	 * Tests that generate_result returns WP_Error when prevent prompt filter returns true.
 	 *

tests/phpunit/tests/ai-client/wpSupportsAI.php

@@ -0,0 +1,30 @@
+<?php
+/**
+ * Tests for wp_supports_ai().
+ *
+ * @group ai-client
+ * @covers ::wp_supports_ai
+ */
+
+class Tests_WP_Supports_AI extends WP_UnitTestCase {
+	/**
+	 * Test that wp_supports_ai() defaults to true.
+	 *
+	 * @ticket 64591
+	 */
+	public function test_defaults_to_true(): void {
+		$this->assertTrue( wp_supports_ai() );
+	}
+
+	/**
+	 * Tests that the wp_supports_ai filter can disable/enable AI features.
+	 */
+	public function test_filter_can_disable_ai_features(): void {
+		add_filter( 'wp_supports_ai', '__return_false' );
+		$this->assertFalse( wp_supports_ai() );
+
+		// Try a later filter to re-enable AI and confirm that it works.
+		add_filter( 'wp_supports_ai', '__return_true' );
+		$this->assertTrue( wp_supports_ai() );
+	}
+}

tests/phpunit/tests/connectors/wpConnectorRegistry.php

@@ -381,4 +381,16 @@ public function test_get_instance_returns_same_instance() {
 
 		$this->assertSame( $instance1, $instance2 );
 	}
+
+	/**
+	 * Test registration skips AI connectors when AI is not supported.
+	 */
+	public function test_register_skips_when_ai_not_supported() {
+		add_filter( 'wp_supports_ai', '__return_false' );
+
+		$this->registry->register( 'first', self::$default_args );
+
+		$all = $this->registry->get_all_registered();
+		$this->assertCount( 0, $all );
+	}
 }