Networks and Sites: add a general pre_site_option filter to get_network_option().

This change brings `get_network_option()` up-to-speed with `get_option()` by adding a more generalized way to short-circuit its return value.

It also introduces 2 new unit tests: one to mirror an existing `pre_option` test, and another to confirm that this new filter is working as intended.

Props audrasjb, Drivingralle, johnjamesjacoby, jorbin, nimeshatxecurify, rollybueno, shailu25, welcher, westonruter.

See #37930, r54145.

Fixes #56870.

git-svn-id: https://develop.svn.wordpress.org/trunk@60959 602fd350-edb4-49c9-b593-d223f7449a82

Author: JJJ

src/wp-includes/option.php

@@ -134,8 +134,8 @@ function get_option( $option, $default_value = false ) {
 	/**
 	 * Filters the value of all existing options before it is retrieved.
 	 *
-	 * Returning a truthy value from the filter will effectively short-circuit retrieval
-	 * and return the passed value instead.
+	 * Returning a value other than false from the filter will short-circuit retrieval
+	 * and return that value instead.
 	 *
 	 * @since 6.1.0
 	 *
@@ -2037,6 +2037,25 @@ function get_network_option( $network_id, $option, $default_value = false ) {
 	 */
 	$pre = apply_filters( "pre_site_option_{$option}", false, $option, $network_id, $default_value );
 
+	/**
+	 * Filters the value of an existing network options before it is retrieved.
+	 *
+	 * Returning a value other than false from the filter will short-circuit retrieval
+	 * and return that value instead.
+	 *
+	 * @since 6.9.0
+	 *
+	 * @param mixed  $pre             The value to return instead of the network option value. This differs
+	 *                                from `$default`, which is used as the fallback value in the event
+	 *                                the option doesn't exist elsewhere in get_network_option().
+	 *                                Default false (to skip past the short-circuit).
+	 * @param string $option          Name of the option.
+	 * @param int    $network_id      ID of the network.
+	 * @param mixed  $default_value   The fallback value to return if the option does not exist.
+	 *                                Default false.
+	 */
+	$pre = apply_filters( 'pre_site_option', $pre, $option, $network_id, $default_value );
+
 	if ( false !== $pre ) {
 		return $pre;
 	}

tests/phpunit/tests/option/networkOption.php

@@ -420,4 +420,54 @@ public function test_delete_network_option_does_not_use_single_site_notoptions_c
 		$this->assertIsArray( $network_notoptions_cache_after, 'Multisite notoptions cache should be set.' );
 		$this->assertArrayHasKey( 'ticket_61730_notoption', $network_notoptions_cache_after, 'The option should be in the notoptions cache.' );
 	}
+
+	/**
+	 * Assert that the 'pre_site_option' hook is called once per call to get_network_option().
+	 *
+	 * @ticket 56870
+	 *
+	 * @group ms-required
+	 *
+	 * @covers ::get_network_option
+	 */
+	public function test_get_network_option_should_call_pre_site_option_filter() {
+		$filter = new MockAction();
+
+		add_filter( 'pre_site_option', array( $filter, 'filter' ) );
+
+		get_network_option( get_current_network_id(), 'ignored' );
+
+		$this->assertSame( 1, $filter->get_call_count() );
+	}
+
+	/**
+	 * Verifies that the global 'pre_site_option' filter short-circuits get_network_option().
+	 *
+	 * @ticket 56870
+	 *
+	 * @group ms-required
+	 *
+	 * @covers ::get_network_option
+	 */
+	public function test_pre_site_option_filter_short_circuits_get_network_option() {
+		$option       = 'ticket_56870_pre_site_option_short_circuit';
+		$network_id   = get_current_network_id();
+		$default_val  = 'default-value';
+		$expected_val = 'filtered-value';
+
+		$callback = function ( $pre, $opt, $net_id ) use ( $option, $network_id, $expected_val ) {
+			// Ensure the filter is invoked for the requested option and network, then short-circuit.
+			if ( $opt === $option && (int) $net_id === (int) $network_id ) {
+				return $expected_val;
+			}
+			return $pre;
+		};
+
+		add_filter( 'pre_site_option', $callback, 10, 3 );
+
+		$actual_val = get_network_option( $network_id, $option, $default_val );
+
+		// The global pre filter should short-circuit and return $expected_val regardless of storage or default.
+		$this->assertSame( $expected_val, $actual_val );
+	}
 }

tests/phpunit/tests/option/option.php

@@ -86,6 +86,8 @@ public function test_add_option_should_respect_default_option_filter() {
 	}
 
 	/**
+	 * Assert that the 'pre_option' hook is called once per call to get_option().
+	 *
 	 * @ticket 37930
 	 *
 	 * @covers ::get_option