Wordpress 4.6

[autoinstalls/wordpress.git] / wp-includes / option.php

diff --git a/wp-includes/option.php b/wp-includes/option.php
index 842981dd4850cc217452136df201209f723c398c..2f3cdd1e7527be5a3ad5a34892c9a869ff383682 100644 (file)
--- a/wp-includes/option.php
+++ b/wp-includes/option.php
@@ -7,7 +7,7 @@
  */
 
 /**
- * Retrieve option value based on name of option.
+ * Retrieves an option value based on an option name.
  *
  * If the option does not exist or does not have a value, then the return value
  * will be false. This is useful to check whether you need to install an option
@@ -16,8 +16,8 @@
  *
  * If the option was serialized then it will be unserialized when it is returned.
  *
- * Any scalar values will be returned as strings. You may coerce the return type of a given option by registering a
- * 'option_{$option}' filter callback.
+ * Any scalar values will be returned as strings. You may coerce the return type of
+ * a given option by registering an {@see 'option_$option'} filter callback.
  *
  * @since 1.5.0
  *
@@ -35,7 +35,7 @@ function get_option( $option, $default = false ) {
                return false;
 
        /**
-        * Filter the value of an existing option before it is retrieved.
+        * Filters the value of an existing option before it is retrieved.
         *
         * The dynamic portion of the hook name, `$option`, refers to the option name.
         *
@@ -61,7 +61,7 @@ function get_option( $option, $default = false ) {
                $notoptions = wp_cache_get( 'notoptions', 'options' );
                if ( isset( $notoptions[ $option ] ) ) {
                        /**
-                        * Filter the default value for an option.
+                        * Filters the default value for an option.
                         *
                         * The dynamic portion of the hook name, `$option`, refers to the option name.
                         *
@@ -121,7 +121,7 @@ function get_option( $option, $default = false ) {
                $value = untrailingslashit( $value );
 
        /**
-        * Filter the value of an existing option.
+        * Filters the value of an existing option.
         *
         * The dynamic portion of the hook name, `$option`, refers to the option name.
         *
@@ -266,7 +266,7 @@ function update_option( $option, $value, $autoload = null ) {
        $old_value = get_option( $option );
 
        /**
-        * Filter a specific option before its value is (maybe) serialized and updated.
+        * Filters a specific option before its value is (maybe) serialized and updated.
         *
         * The dynamic portion of the hook name, `$option`, refers to the option name.
         *
@@ -280,7 +280,7 @@ function update_option( $option, $value, $autoload = null ) {
        $value = apply_filters( 'pre_update_option_' . $option, $value, $old_value, $option );
 
        /**
-        * Filter an option before its value is (maybe) serialized and updated.
+        * Filters an option before its value is (maybe) serialized and updated.
         *
         * @since 3.9.0
         *
@@ -295,7 +295,7 @@ function update_option( $option, $value, $autoload = null ) {
                return false;
 
        /** This filter is documented in wp-includes/option.php */
-       if ( apply_filters( 'default_option_' . $option, false ) === $old_value ) {
+       if ( apply_filters( 'default_option_' . $option, false, $option ) === $old_value ) {
                // Default setting for new options is 'yes'.
                if ( null === $autoload ) {
                        $autoload = 'yes';
@@ -399,7 +399,7 @@ function add_option( $option, $value = '', $deprecated = '', $autoload = 'yes' )
        global $wpdb;
 
        if ( !empty( $deprecated ) )
-               _deprecated_argument( __FUNCTION__, '2.3' );
+               _deprecated_argument( __FUNCTION__, '2.3.0' );
 
        $option = trim($option);
        if ( empty($option) )
@@ -416,7 +416,7 @@ function add_option( $option, $value = '', $deprecated = '', $autoload = 'yes' )
        $notoptions = wp_cache_get( 'notoptions', 'options' );
        if ( !is_array( $notoptions ) || !isset( $notoptions[$option] ) )
                /** This filter is documented in wp-includes/option.php */
-               if ( apply_filters( 'default_option_' . $option, false ) !== get_option( $option ) )
+               if ( apply_filters( 'default_option_' . $option, false, $option ) !== get_option( $option ) )
                        return false;
 
        $serialized_value = maybe_serialize( $value );
@@ -609,7 +609,7 @@ function delete_transient( $transient ) {
 function get_transient( $transient ) {
 
        /**
-        * Filter the value of an existing transient.
+        * Filters the value of an existing transient.
         *
         * The dynamic portion of the hook name, `$transient`, refers to the transient name.
         *
@@ -651,7 +651,7 @@ function get_transient( $transient ) {
        }
 
        /**
-        * Filter an existing transient's value.
+        * Filters an existing transient's value.
         *
         * The dynamic portion of the hook name, `$transient`, refers to the transient name.
         *
@@ -684,7 +684,7 @@ function set_transient( $transient, $value, $expiration = 0 ) {
        $expiration = (int) $expiration;
 
        /**
-        * Filter a specific transient before its value is set.
+        * Filters a specific transient before its value is set.
         *
         * The dynamic portion of the hook name, `$transient`, refers to the transient name.
         *
@@ -699,7 +699,7 @@ function set_transient( $transient, $value, $expiration = 0 ) {
        $value = apply_filters( 'pre_set_transient_' . $transient, $value, $expiration, $transient );
 
        /**
-        * Filter the expiration for a transient before its value is set.
+        * Filters the expiration for a transient before its value is set.
         *
         * The dynamic portion of the hook name, `$transient`, refers to the transient name.
         *
@@ -844,13 +844,14 @@ function get_user_setting( $name, $default = false ) {
  * Add or update user interface setting.
  *
  * Both $name and $value can contain only ASCII letters, numbers and underscores.
+ *
  * This function has to be used before any output has started as it calls setcookie().
  *
  * @since 2.8.0
  *
  * @param string $name  The name of the setting.
  * @param string $value The value for the setting.
- * @return bool|void true if set successfully/false if not.
+ * @return bool|null True if set successfully, false if not. Null if the current user can't be established.
  */
 function set_user_setting( $name, $value ) {
        if ( headers_sent() ) {
@@ -867,12 +868,13 @@ function set_user_setting( $name, $value ) {
  * Delete user interface settings.
  *
  * Deleting settings would reset them to the defaults.
+ *
  * This function has to be used before any output has started as it calls setcookie().
  *
  * @since 2.7.0
  *
  * @param string $names The name or array of names of the setting to be deleted.
- * @return bool|void true if deleted successfully/false if not.
+ * @return bool|null True if deleted successfully, false if not. Null if the current user can't be established.
  */
 function delete_user_setting( $names ) {
        if ( headers_sent() ) {
@@ -941,11 +943,13 @@ function get_all_user_settings() {
  * Private. Set all user interface settings.
  *
  * @since 2.8.0
+ * @access private
  *
  * @global array $_updated_user_settings
  *
- * @param array $user_settings
- * @return bool|void
+ * @param array $user_settings User settings.
+ * @return bool|null False if the current user can't be found, null if the current
+ *                   user is not a super admin or a member of the site, otherwise true.
  */
 function wp_set_all_user_settings( $user_settings ) {
        global $_updated_user_settings;
@@ -1088,7 +1092,7 @@ function get_network_option( $network_id, $option, $default = false ) {
        }
 
        /**
-        * Filter an existing network option before it is retrieved.
+        * Filters an existing network option before it is retrieved.
         *
         * The dynamic portion of the hook name, `$option`, refers to the option name.
         *
@@ -1115,7 +1119,7 @@ function get_network_option( $network_id, $option, $default = false ) {
        if ( isset( $notoptions[ $option ] ) ) {
 
                /**
-                * Filter a specific default network option.
+                * Filters a specific default network option.
                 *
                 * The dynamic portion of the hook name, `$option`, refers to the option name.
                 *
@@ -1159,7 +1163,7 @@ function get_network_option( $network_id, $option, $default = false ) {
        }
 
        /**
-        * Filter the value of an existing network option.
+        * Filters the value of an existing network option.
         *
         * The dynamic portion of the hook name, `$option`, refers to the option name.
         *
@@ -1207,7 +1211,7 @@ function add_network_option( $network_id, $option, $value ) {
        wp_protect_special_option( $option );
 
        /**
-        * Filter the value of a specific network option before it is added.
+        * Filters the value of a specific network option before it is added.
         *
         * The dynamic portion of the hook name, `$option`, refers to the option name.
         *
@@ -1223,7 +1227,7 @@ function add_network_option( $network_id, $option, $value ) {
        $notoptions_key = "$network_id:notoptions";
 
        if ( ! is_multisite() ) {
-               $result = add_option( $option, $value );
+               $result = add_option( $option, $value, '', 'no' );
        } else {
                $cache_key = "$network_id:$option";
 
@@ -1401,7 +1405,7 @@ function update_network_option( $network_id, $option, $value ) {
        $old_value = get_network_option( $network_id, $option, false );
 
        /**
-        * Filter a specific network option before its value is updated.
+        * Filters a specific network option before its value is updated.
         *
         * The dynamic portion of the hook name, `$option`, refers to the option name.
         *
@@ -1431,7 +1435,7 @@ function update_network_option( $network_id, $option, $value ) {
        }
 
        if ( ! is_multisite() ) {
-               $result = update_option( $option, $value );
+               $result = update_option( $option, $value, 'no' );
        } else {
                $value = sanitize_option( $option, $value );
 
@@ -1538,7 +1542,7 @@ function delete_site_transient( $transient ) {
 function get_site_transient( $transient ) {
 
        /**
-        * Filter the value of an existing site transient.
+        * Filters the value of an existing site transient.
         *
         * The dynamic portion of the hook name, `$transient`, refers to the transient name.
         *
@@ -1579,7 +1583,7 @@ function get_site_transient( $transient ) {
        }
 
        /**
-        * Filter the value of an existing site transient.
+        * Filters the value of an existing site transient.
         *
         * The dynamic portion of the hook name, `$transient`, refers to the transient name.
         *
@@ -1611,7 +1615,7 @@ function get_site_transient( $transient ) {
 function set_site_transient( $transient, $value, $expiration = 0 ) {
 
        /**
-        * Filter the value of a specific site transient before it is set.
+        * Filters the value of a specific site transient before it is set.
         *
         * The dynamic portion of the hook name, `$transient`, refers to the transient name.
         *
@@ -1626,7 +1630,7 @@ function set_site_transient( $transient, $value, $expiration = 0 ) {
        $expiration = (int) $expiration;
 
        /**
-        * Filter the expiration for a site transient before its value is set.
+        * Filters the expiration for a site transient before its value is set.
         *
         * The dynamic portion of the hook name, `$transient`, refers to the transient name.
         *