WordPress.org

Make WordPress Core

Changeset 34777


Ignore:
Timestamp:
10/02/2015 06:00:30 PM (3 years ago)
Author:
jeremyfelt
Message:

MS: Introduce *_network_option functions.

Introduces add_network_option(), update_network_option(), get_network_option(), and delete_network_option(), which use the internals previously found in the *_site_option() functions and allow for a network ID to enable cross network storage and retrieval of network options.

  • *_site_option() functions are now wrappers for *_network_option() and will interact with options for the current network in a multisite environment.
  • All will continue to fallback to *_option() for non-multisite uses.
  • Adds basic tests for cross network storage and retrieval.
  • Existing tests for *_site_option() functions provide coverage for storage and retrieval of current network options.

Props spacedmonkey, DrewAPicture, jeremyfelt.
See #28290.

Location:
trunk
Files:
1 added
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/option.php

    r34756 r34777  
    973973
    974974/**
    975  * Retrieve site option value based on name of option.
     975 * Retrieve an option value for the current network based on name of option.
    976976 *
    977977 * @since 2.8.0
     978 * @since 4.4.0 Modified into wrapper for get_network_option()
     979 *
     980 * @see get_network_option()
     981 *
     982 * @param string $option     Name of option to retrieve. Expected to not be SQL-escaped.
     983 * @param mixed  $default    Optional value to return if option doesn't exist. Default false.
     984 * @param bool   $deprecated Whether to use cache. Multisite only. Always set to true.
     985 * @return mixed Value set for the option.
     986 */
     987function get_site_option( $option, $default = false, $deprecated = true ) {
     988    return get_network_option( $option, $default );
     989}
     990
     991/**
     992 * Add a new option for the current network.
     993 *
     994 * Existing options will not be updated. Note that prior to 3.3 this wasn't the case.
     995 *
     996 * @since 2.8.0
     997 * @since 4.4.0 Modified into wrapper for add_network_option()
     998 *
     999 * @see add_network_option()
     1000 *
     1001 * @param string $option Name of option to add. Expected to not be SQL-escaped.
     1002 * @param mixed  $value  Option value, can be anything. Expected to not be SQL-escaped.
     1003 * @return bool False if the option was not added. True if the option was added.
     1004 */
     1005function add_site_option( $option, $value ) {
     1006    return add_network_option( $option, $value );
     1007}
     1008
     1009/**
     1010 * Removes a option by name for the current network.
     1011 *
     1012 * @since 2.8.0
     1013 * @since 4.4.0 Modified into wrapper for delete_network_option()
     1014 *
     1015 * @see delete_network_option()
     1016 *
     1017 * @param string $option Name of option to remove. Expected to not be SQL-escaped.
     1018 * @return bool True, if succeed. False, if failure.
     1019 */
     1020function delete_site_option( $option ) {
     1021    return delete_network_option( $option );
     1022}
     1023
     1024/**
     1025 * Update the value of an option that was already added for the current network.
     1026 *
     1027 * @since 2.8.0
     1028 * @since 4.4.0 Modified into wrapper for update_network_option()
     1029 *
     1030 * @see update_network_option()
     1031 *
     1032 * @param string $option Name of option. Expected to not be SQL-escaped.
     1033 * @param mixed  $value  Option value. Expected to not be SQL-escaped.
     1034 * @return bool False if value was not updated. True if value was updated.
     1035 */
     1036function update_site_option( $option, $value ) {
     1037    return update_network_option( $option, $value );
     1038}
     1039
     1040/**
     1041 * Retrieve a network's option value based on the option name.
     1042 *
     1043 * @since 4.4.0
    9781044 *
    9791045 * @see get_option()
    9801046 *
    981  * @global wpdb $wpdb
    982  *
    983  * @param string $option    Name of option to retrieve. Expected to not be SQL-escaped.
    984  * @param mixed  $default   Optional value to return if option doesn't exist. Default false.
    985  * @param bool   $use_cache Whether to use cache. Multisite only. Default true.
     1047 * @global wpdb   $wpdb
     1048 * @global object $current_site
     1049 *
     1050 * @param string   $option     Name of option to retrieve. Expected to not be SQL-escaped.
     1051 * @param mixed    $default    Optional. Value to return if the option doesn't exist. Default false.
     1052 * @param int|bool $network_id Optional. ID of the network. Defaults to current network ID.
    9861053 * @return mixed Value set for the option.
    9871054 */
    988 function get_site_option( $option, $default = false, $use_cache = true ) {
    989     global $wpdb;
    990 
    991     /**
    992      * Filter an existing site option before it is retrieved.
     1055function get_network_option( $option, $default = false, $network_id = false ) {
     1056    global $wpdb, $current_site;
     1057
     1058    $network_id = (int) $network_id;
     1059
     1060    // Fallback to the current network if a network ID is not specified.
     1061    if ( ! $network_id && is_multisite() ) {
     1062        $network_id = $current_site->id;
     1063    }
     1064
     1065    /**
     1066     * Filter an existing network option before it is retrieved.
    9931067     *
    9941068     * The dynamic portion of the hook name, `$option`, refers to the option name.
     
    10061080    $pre = apply_filters( 'pre_site_option_' . $option, false, $option );
    10071081
    1008     if ( false !== $pre )
    1009         return $pre;
     1082    if ( false !== $pre ) {
     1083        return $pre;
     1084    }
    10101085
    10111086    // prevent non-existent options from triggering multiple queries
    1012     $notoptions_key = "{$wpdb->siteid}:notoptions";
     1087    $notoptions_key = "$network_id:notoptions";
    10131088    $notoptions = wp_cache_get( $notoptions_key, 'site-options' );
    10141089
    1015     if ( isset( $notoptions[$option] ) ) {
     1090    if ( isset( $notoptions[ $option ] ) ) {
    10161091
    10171092        /**
    1018          * Filter a specific default site option.
     1093         * Filter a specific default network option.
    10191094         *
    10201095         * The dynamic portion of the hook name, `$option`, refers to the option name.
     
    10311106
    10321107    if ( ! is_multisite() ) {
    1033 
    10341108        /** This filter is documented in wp-includes/option.php */
    10351109        $default = apply_filters( 'default_site_option_' . $option, $default, $option );
    1036         $value = get_option($option, $default);
     1110        $value = get_option( $option, $default );
    10371111    } else {
    1038         $cache_key = "{$wpdb->siteid}:$option";
    1039         if ( $use_cache )
    1040             $value = wp_cache_get($cache_key, 'site-options');
    1041 
    1042         if ( !isset($value) || (false === $value) ) {
    1043             $row = $wpdb->get_row( $wpdb->prepare("SELECT meta_value FROM $wpdb->sitemeta WHERE meta_key = %s AND site_id = %d", $option, $wpdb->siteid ) );
     1112        $cache_key = "$network_id:$option";
     1113        $value = wp_cache_get( $cache_key, 'site-options' );
     1114
     1115        if ( ! isset( $value ) || false === $value ) {
     1116            $row = $wpdb->get_row( $wpdb->prepare( "SELECT meta_value FROM $wpdb->sitemeta WHERE meta_key = %s AND site_id = %d", $option, $network_id ) );
    10441117
    10451118            // Has to be get_row instead of get_var because of funkiness with 0, false, null values
     
    10501123            } else {
    10511124                if ( ! is_array( $notoptions ) ) {
    1052                      $notoptions = array();
     1125                    $notoptions = array();
    10531126                }
    1054                 $notoptions[$option] = true;
     1127                $notoptions[ $option ] = true;
    10551128                wp_cache_set( $notoptions_key, $notoptions, 'site-options' );
    10561129
     
    10621135
    10631136    /**
    1064      * Filter the value of an existing site option.
     1137     * Filter the value of an existing network option.
    10651138     *
    10661139     * The dynamic portion of the hook name, `$option`, refers to the option name.
     
    10701143     * @since 4.4.0 The `$option` parameter was added
    10711144     *
    1072      * @param mixed  $value  Value of site option.
     1145     * @param mixed  $value  Value of network option.
    10731146     * @param string $option Option name.
    10741147     */
     
    10771150
    10781151/**
    1079  * Add a new site option.
    1080  *
    1081  * Existing options will not be updated. Note that prior to 3.3 this wasn't the case.
    1082  *
    1083  * @since 2.8.0
     1152 * Add a new network option.
     1153 *
     1154 * Existing options will not be updated.
     1155 *
     1156 * @since 4.4.0
    10841157 *
    10851158 * @see add_option()
    10861159 *
    1087  * @global wpdb $wpdb
    1088  *
    1089  * @param string $option Name of option to add. Expected to not be SQL-escaped.
    1090  * @param mixed  $value  Optional. Option value, can be anything. Expected to not be SQL-escaped.
     1160 * @global wpdb   $wpdb
     1161 * @global object $current_site
     1162 *
     1163 * @param  string   $option     Name of option to add. Expected to not be SQL-escaped.
     1164 * @param  mixed    $value      Option value, can be anything. Expected to not be SQL-escaped.
     1165 * @param  int|bool $network_id Optional. ID of the network. Defaults to current network ID.
    10911166 * @return bool False if option was not added and true if option was added.
    10921167 */
    1093 function add_site_option( $option, $value ) {
    1094     global $wpdb;
     1168function add_network_option( $option, $value, $network_id = false ) {
     1169    global $wpdb, $current_site;
     1170
     1171    $network_id = (int) $network_id;
     1172
     1173    // Fallback to the current network if a network ID is not specified.
     1174    if ( ! $network_id && is_multisite() ) {
     1175        $network_id = $current_site->id;
     1176    }
    10951177
    10961178    wp_protect_special_option( $option );
    10971179
    10981180    /**
    1099      * Filter the value of a specific site option before it is added.
     1181     * Filter the value of a specific network option before it is added.
    11001182     *
    11011183     * The dynamic portion of the hook name, `$option`, refers to the option name.
     
    11051187     * @since 4.4.0 The `$option` parameter was added
    11061188     *
    1107      * @param mixed  $value  Value of site option.
     1189     * @param mixed  $value  Value of network option.
    11081190     * @param string $option Option name.
    11091191     */
    11101192    $value = apply_filters( 'pre_add_site_option_' . $option, $value, $option );
    11111193
    1112     $notoptions_key = "{$wpdb->siteid}:notoptions";
    1113 
    1114     if ( !is_multisite() ) {
     1194    $notoptions_key = "$network_id:notoptions";
     1195
     1196    if ( ! is_multisite() ) {
    11151197        $result = add_option( $option, $value );
    11161198    } else {
    1117         $cache_key = "{$wpdb->siteid}:$option";
     1199        $cache_key = "$network_id:$option";
    11181200
    11191201        // Make sure the option doesn't already exist. We can check the 'notoptions' cache before we ask for a db query
    11201202        $notoptions = wp_cache_get( $notoptions_key, 'site-options' );
    1121         if ( ! is_array( $notoptions ) || ! isset( $notoptions[$option] ) )
    1122             if ( false !== get_site_option( $option ) )
     1203        if ( ! is_array( $notoptions ) || ! isset( $notoptions[ $option ] ) ) {
     1204            if ( false !== get_network_option( $option, false, $network_id ) ) {
    11231205                return false;
     1206            }
     1207        }
    11241208
    11251209        $value = sanitize_option( $option, $value );
    11261210
    11271211        $serialized_value = maybe_serialize( $value );
    1128         $result = $wpdb->insert( $wpdb->sitemeta, array('site_id' => $wpdb->siteid, 'meta_key' => $option, 'meta_value' => $serialized_value ) );
    1129 
    1130         if ( ! $result )
     1212        $result = $wpdb->insert( $wpdb->sitemeta, array( 'site_id'    => $network_id, 'meta_key'  => $option, 'meta_value' => $serialized_value ) );
     1213
     1214        if ( ! $result ) {
    11311215            return false;
     1216        }
    11321217
    11331218        wp_cache_set( $cache_key, $value, 'site-options' );
     
    11351220        // This option exists now
    11361221        $notoptions = wp_cache_get( $notoptions_key, 'site-options' ); // yes, again... we need it to be fresh
    1137         if ( is_array( $notoptions ) && isset( $notoptions[$option] ) ) {
    1138             unset( $notoptions[$option] );
     1222        if ( is_array( $notoptions ) && isset( $notoptions[ $option ] ) ) {
     1223            unset( $notoptions[ $option ] );
    11391224            wp_cache_set( $notoptions_key, $notoptions, 'site-options' );
    11401225        }
     
    11441229
    11451230        /**
    1146          * Fires after a specific site option has been successfully added.
     1231         * Fires after a specific network option has been successfully added.
    11471232         *
    11481233         * The dynamic portion of the hook name, `$option`, refers to the option name.
     
    11511236         * @since 3.0.0
    11521237         *
    1153          * @param string $option Name of site option.
    1154          * @param mixed  $value  Value of site option.
     1238         * @param string $option Name of the network option.
     1239         * @param mixed  $value  Value of the network option.
    11551240         */
    1156         do_action( "add_site_option_{$option}", $option, $value );
     1241        do_action( 'add_site_option_' . $option, $option, $value );
    11571242
    11581243        /**
    1159          * Fires after a site option has been successfully added.
     1244         * Fires after a network option has been successfully added.
    11601245         *
    11611246         * @since 3.0.0
    11621247         *
    1163          * @param string $option Name of site option.
    1164          * @param mixed  $value  Value of site option.
     1248         * @param string $option Name of the network option.
     1249         * @param mixed  $value  Value of the network option.
    11651250         */
    1166         do_action( "add_site_option", $option, $value );
     1251        do_action( 'add_site_option', $option, $value );
    11671252
    11681253        return true;
    11691254    }
     1255
    11701256    return false;
    11711257}
    11721258
    11731259/**
    1174  * Removes site option by name.
    1175  *
    1176  * @since 2.8.0
     1260 * Removes a network option by name.
     1261 *
     1262 * @since 4.4.0
    11771263 *
    11781264 * @see delete_option()
    11791265 *
    1180  * @global wpdb $wpdb
    1181  *
    1182  * @param string $option Name of option to remove. Expected to not be SQL-escaped.
     1266 * @global wpdb   $wpdb
     1267 * @global object $current_site
     1268 *
     1269 * @param  string   $option     Name of option to remove. Expected to not be SQL-escaped.
     1270 * @param  int|bool $network_id Optional. ID of the network. Defaults to current network ID.
    11831271 * @return bool True, if succeed. False, if failure.
    11841272 */
    1185 function delete_site_option( $option ) {
    1186     global $wpdb;
    1187 
    1188     /**
    1189      * Fires immediately before a specific site option is deleted.
     1273function delete_network_option( $option, $network_id = false ) {
     1274    global $wpdb, $current_site;
     1275
     1276    $network_id = (int) $network_id;
     1277
     1278    // Fallback to the current network if a network ID is not specified.
     1279    if ( ! $network_id && is_multisite() ) {
     1280        $network_id = $current_site->id;
     1281    }
     1282
     1283    /**
     1284     * Fires immediately before a specific network option is deleted.
    11901285     *
    11911286     * The dynamic portion of the hook name, `$option`, refers to the option name.
     
    11981293    do_action( 'pre_delete_site_option_' . $option, $option );
    11991294
    1200     if ( !is_multisite() ) {
     1295    if ( ! is_multisite() ) {
    12011296        $result = delete_option( $option );
    12021297    } else {
    1203         $row = $wpdb->get_row( $wpdb->prepare( "SELECT meta_id FROM {$wpdb->sitemeta} WHERE meta_key = %s AND site_id = %d", $option, $wpdb->siteid ) );
    1204         if ( is_null( $row ) || !$row->meta_id )
     1298        $row = $wpdb->get_row( $wpdb->prepare( "SELECT meta_id FROM {$wpdb->sitemeta} WHERE meta_key = %s AND site_id = %d", $option, $network_id ) );
     1299        if ( is_null( $row ) || ! $row->meta_id ) {
    12051300            return false;
    1206         $cache_key = "{$wpdb->siteid}:$option";
     1301        }
     1302        $cache_key = "$network_id:$option";
    12071303        wp_cache_delete( $cache_key, 'site-options' );
    12081304
    1209         $result = $wpdb->delete( $wpdb->sitemeta, array( 'meta_key' => $option, 'site_id' => $wpdb->siteid ) );
     1305        $result = $wpdb->delete( $wpdb->sitemeta, array( 'meta_key' => $option, 'site_id' => $network_id ) );
    12101306    }
    12111307
     
    12131309
    12141310        /**
    1215          * Fires after a specific site option has been deleted.
     1311         * Fires after a specific network option has been deleted.
    12161312         *
    12171313         * The dynamic portion of the hook name, `$option`, refers to the option name.
     
    12201316         * @since 3.0.0
    12211317         *
    1222          * @param string $option Name of the site option.
     1318         * @param string $option Name of the network option.
    12231319         */
    1224         do_action( "delete_site_option_{$option}", $option );
     1320        do_action( 'delete_site_option_' . $option, $option );
    12251321
    12261322        /**
    1227          * Fires after a site option has been deleted.
     1323         * Fires after a network option has been deleted.
    12281324         *
    12291325         * @since 3.0.0
    12301326         *
    1231          * @param string $option Name of the site option.
     1327         * @param string $option Name of the network option.
    12321328         */
    1233         do_action( "delete_site_option", $option );
     1329        do_action( 'delete_site_option', $option );
    12341330
    12351331        return true;
    12361332    }
     1333
    12371334    return false;
    12381335}
    12391336
    12401337/**
    1241  * Update the value of a site option that was already added.
    1242  *
    1243  * @since 2.8.0
     1338 * Update the value of a network option that was already added.
     1339 *
     1340 * @since 4.4.0
    12441341 *
    12451342 * @see update_option()
    12461343 *
    1247  * @global wpdb $wpdb
    1248  *
    1249  * @param string $option Name of option. Expected to not be SQL-escaped.
    1250  * @param mixed  $value  Option value. Expected to not be SQL-escaped.
     1344 * @global wpdb   $wpdb
     1345 * @global object $current_site
     1346 *
     1347 * @param string   $option     Name of option. Expected to not be SQL-escaped.
     1348 * @param mixed    $value      Option value. Expected to not be SQL-escaped.
     1349 * @param int|bool $network_id Optional. ID of the network. Defaults to current network ID.
    12511350 * @return bool False if value was not updated and true if value was updated.
    12521351 */
    1253 function update_site_option( $option, $value ) {
    1254     global $wpdb;
     1352function update_network_option( $option, $value, $network_id = false ) {
     1353    global $wpdb, $current_site;
     1354
     1355    $network_id = (int) $network_id;
     1356
     1357    // Fallback to the current network if a network ID is not specified.
     1358    if ( ! $network_id && is_multisite() ) {
     1359        $network_id = $current_site->id;
     1360    }
    12551361
    12561362    wp_protect_special_option( $option );
    12571363
    1258     $old_value = get_site_option( $option );
    1259 
    1260     /**
    1261      * Filter a specific site option before its value is updated.
     1364    $old_value = get_network_option( $option, false, $network_id );
     1365
     1366    /**
     1367     * Filter a specific network option before its value is updated.
    12621368     *
    12631369     * The dynamic portion of the hook name, `$option`, refers to the option name.
     
    12671373     * @since 4.4.0 The `$option` parameter was added
    12681374     *
    1269      * @param mixed  $value     New value of site option.
    1270      * @param mixed  $old_value Old value of site option.
     1375     * @param mixed  $value     New value of the network option.
     1376     * @param mixed  $old_value Old value of the network option.
    12711377     * @param string $option    Option name.
    12721378     */
    12731379    $value = apply_filters( 'pre_update_site_option_' . $option, $value, $old_value, $option );
    12741380
    1275     if ( $value === $old_value )
     1381    if ( $value === $old_value ) {
    12761382        return false;
    1277 
    1278     if ( false === $old_value )
    1279         return add_site_option( $option, $value );
    1280 
    1281     $notoptions_key = "{$wpdb->siteid}:notoptions";
     1383    }
     1384
     1385    if ( false === $old_value ) {
     1386        return add_network_option( $option, $value, $network_id );
     1387    }
     1388
     1389    $notoptions_key = "$network_id:notoptions";
    12821390    $notoptions = wp_cache_get( $notoptions_key, 'site-options' );
    1283     if ( is_array( $notoptions ) && isset( $notoptions[$option] ) ) {
    1284         unset( $notoptions[$option] );
     1391    if ( is_array( $notoptions ) && isset( $notoptions[ $option ] ) ) {
     1392        unset( $notoptions[ $option ] );
    12851393        wp_cache_set( $notoptions_key, $notoptions, 'site-options' );
    12861394    }
    12871395
    1288     if ( !is_multisite() ) {
     1396    if ( ! is_multisite() ) {
    12891397        $result = update_option( $option, $value );
    12901398    } else {
     
    12921400
    12931401        $serialized_value = maybe_serialize( $value );
    1294         $result = $wpdb->update( $wpdb->sitemeta, array( 'meta_value' => $serialized_value ), array( 'site_id' => $wpdb->siteid, 'meta_key' => $option ) );
     1402        $result = $wpdb->update( $wpdb->sitemeta, array( 'meta_value' => $serialized_value ), array( 'site_id' => $network_id, 'meta_key' => $option ) );
    12951403
    12961404        if ( $result ) {
    1297             $cache_key = "{$wpdb->siteid}:$option";
     1405            $cache_key = "$network_id:$option";
    12981406            wp_cache_set( $cache_key, $value, 'site-options' );
    12991407        }
     
    13031411
    13041412        /**
    1305          * Fires after the value of a specific site option has been successfully updated.
     1413         * Fires after the value of a specific network option has been successfully updated.
    13061414         *
    13071415         * The dynamic portion of the hook name, `$option`, refers to the option name.
     
    13101418         * @since 3.0.0
    13111419         *
    1312          * @param string $option    Name of site option.
    1313          * @param mixed  $value     Current value of site option.
    1314          * @param mixed  $old_value Old value of site option.
     1420         * @param string $option    Name of the network option.
     1421         * @param mixed  $value     Current value of the network option.
     1422         * @param mixed  $old_value Old value of the network option.
    13151423         */
    1316         do_action( "update_site_option_{$option}", $option, $value, $old_value );
     1424        do_action( 'update_site_option_' . $option, $option, $value, $old_value );
    13171425
    13181426        /**
    1319          * Fires after the value of a site option has been successfully updated.
     1427         * Fires after the value of a network option has been successfully updated.
    13201428         *
    13211429         * @since 3.0.0
    13221430         *
    1323          * @param string $option    Name of site option.
    1324          * @param mixed  $value     Current value of site option.
    1325          * @param mixed  $old_value Old value of site option.
     1431         * @param string $option    Name of the network option.
     1432         * @param mixed  $value     Current value of the network option.
     1433         * @param mixed  $old_value Old value of the network option.
    13261434         */
    1327         do_action( "update_site_option", $option, $value, $old_value );
     1435        do_action( 'update_site_option', $option, $value, $old_value );
    13281436
    13291437        return true;
    13301438    }
     1439
    13311440    return false;
    13321441}
Note: See TracChangeset for help on using the changeset viewer.