Changeset 60959

Timestamp:

10/17/2025 06:46:42 PM (4 months ago)

Author:

johnjamesjacoby

Message:

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.

Location:

trunk

Files:

• src/wp-includes/option.php (modified) (2 diffs)
• tests/phpunit/tests/option/networkOption.php (modified) (1 diff)
• tests/phpunit/tests/option/option.php (modified) (1 diff)

trunk/src/wp-includes/option.php

@@ -135 +135 @@
      * 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
@@ -2038 +2038 @@
     $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;

trunk/tests/phpunit/tests/option/networkOption.php

@@ -421 +421 @@
         $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 );
+    }
 }

trunk/tests/phpunit/tests/option/option.php

@@ -87 +87 @@
 
     /**
+     * Assert that the 'pre_option' hook is called once per call to get_option().
+     *
      * @ticket 37930
      *