update_option( string $option, mixed $value, string|bool $autoload = null )
Met à jour la valeur d'une option.
Paramètres
$option(string)requisNom de l'option à mettre à jour.
$value(mixed)requisValeur de l'option.
$autoload(string|bool)optionnelCharge l'option quand Wordpress démarre. Pour les options existantes, $autoload peut aussi être mise à jour en utilisant update_option() si $value est aussi changée. Accepte 'yes' | true pour autoriser ou 'no' | false pour désactiver. Pour les options non-existantes la valeur par défaut est 'yes'.
Valeur par défaut : null
Description / Informations supplémentaires
Si la valeur doit être sérializer, elle le sera avant d'être insérer en base de donné.
Si l'option n'existe pas, elle sera créer.
Retourne
(bool) True si la valeur a été mise à jour, false autrement.
Déclaration et structure de la fonction update_option()
update_option() est déclarée dans le fichier wp-includes/option.php à la ligne 826 :
function update_option( $option, $value, $autoload = null ) {
global $wpdb;
if ( is_scalar( $option ) ) {
$option = trim( $option );
}
if ( empty( $option ) ) {
return false;
}
/*
* Until a proper _deprecated_option() function can be introduced,
* redirect requests to deprecated keys to the new, correct ones.
*/
$deprecated_keys = array(
'blacklist_keys' => 'disallowed_keys',
'comment_whitelist' => 'comment_previously_approved',
);
if ( isset( $deprecated_keys[ $option ] ) && ! wp_installing() ) {
_deprecated_argument(
__FUNCTION__,
'5.5.0',
sprintf(
/* translators: 1: Deprecated option key, 2: New option key. */
__( 'The "%1$s" option key has been renamed to "%2$s".' ),
$option,
$deprecated_keys[ $option ]
)
);
return update_option( $deprecated_keys[ $option ], $value, $autoload );
}
wp_protect_special_option( $option );
if ( is_object( $value ) ) {
$value = clone $value;
}
$value = sanitize_option( $option, $value );
$old_value = get_option( $option );
/**
* 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.
*
* @since 2.6.0
* @since 4.4.0 The `$option` parameter was added.
*
* @param mixed $value The new, unserialized option value.
* @param mixed $old_value The old option value.
* @param string $option Option name.
*/
$value = apply_filters( "pre_update_option_{$option}", $value, $old_value, $option );
/**
* Filters an option before its value is (maybe) serialized and updated.
*
* @since 3.9.0
*
* @param mixed $value The new, unserialized option value.
* @param string $option Name of the option.
* @param mixed $old_value The old option value.
*/
$value = apply_filters( 'pre_update_option', $value, $option, $old_value );
/*
* If the new and old values are the same, no need to update.
*
* Unserialized values will be adequate in most cases. If the unserialized
* data differs, the (maybe) serialized data is checked to avoid
* unnecessary database calls for otherwise identical object instances.
*
* See https://core.trac.wordpress.org/ticket/38903
*/
if ( $value === $old_value || maybe_serialize( $value ) === maybe_serialize( $old_value ) ) {
return false;
}
/** This filter is documented in wp-includes/option.php */
if ( apply_filters( "default_option_{$option}", false, $option, false ) === $old_value ) {
return add_option( $option, $value, '', $autoload );
}
$serialized_value = maybe_serialize( $value );
/**
* Fires immediately before an option value is updated.
*
* @since 2.9.0
*
* @param string $option Name of the option to update.
* @param mixed $old_value The old option value.
* @param mixed $value The new option value.
*/
do_action( 'update_option', $option, $old_value, $value );
$update_args = array(
'option_value' => $serialized_value,
);
if ( null !== $autoload ) {
$update_args['autoload'] = wp_determine_option_autoload_value( $option, $value, $serialized_value, $autoload );
} else {
// Retrieve the current autoload value to reevaluate it in case it was set automatically.
$raw_autoload = $wpdb->get_var( $wpdb->prepare( "SELECT autoload FROM $wpdb->options WHERE option_name = %s LIMIT 1", $option ) );
$allow_values = array( 'auto-on', 'auto-off', 'auto' );
if ( in_array( $raw_autoload, $allow_values, true ) ) {
$autoload = wp_determine_option_autoload_value( $option, $value, $serialized_value, $autoload );
if ( $autoload !== $raw_autoload ) {
$update_args['autoload'] = $autoload;
}
}
}
$result = $wpdb->update( $wpdb->options, $update_args, array( 'option_name' => $option ) );
if ( ! $result ) {
return false;
}
$notoptions = wp_cache_get( 'notoptions', 'options' );
if ( is_array( $notoptions ) && isset( $notoptions[ $option ] ) ) {
unset( $notoptions[ $option ] );
wp_cache_set( 'notoptions', $notoptions, 'options' );
}
if ( ! wp_installing() ) {
if ( ! isset( $update_args['autoload'] ) ) {
// Update the cached value based on where it is currently cached.
$alloptions = wp_load_alloptions( true );
if ( isset( $alloptions[ $option ] ) ) {
$alloptions[ $option ] = $serialized_value;
wp_cache_set( 'alloptions', $alloptions, 'options' );
} else {
wp_cache_set( $option, $serialized_value, 'options' );
}
} elseif ( in_array( $update_args['autoload'], wp_autoload_values_to_autoload(), true ) ) {
// Delete the individual cache, then set in alloptions cache.
wp_cache_delete( $option, 'options' );
$alloptions = wp_load_alloptions( true );
$alloptions[ $option ] = $serialized_value;
wp_cache_set( 'alloptions', $alloptions, 'options' );
} else {
// Delete the alloptions cache, then set the individual cache.
$alloptions = wp_load_alloptions( true );
if ( isset( $alloptions[ $option ] ) ) {
unset( $alloptions[ $option ] );
wp_cache_set( 'alloptions', $alloptions, 'options' );
}
wp_cache_set( $option, $serialized_value, 'options' );
}
}
/**
* Fires after the value of a specific option has been successfully updated.
*
* The dynamic portion of the hook name, `$option`, refers to the option name.
*
* @since 2.0.1
* @since 4.4.0 The `$option` parameter was added.
*
* @param mixed $old_value The old option value.
* @param mixed $value The new option value.
* @param string $option Option name.
*/
do_action( "update_option_{$option}", $old_value, $value, $option );
/**
* Fires after the value of an option has been successfully updated.
*
* @since 2.9.0
*
* @param string $option Name of the updated option.
* @param mixed $old_value The old option value.
* @param mixed $value The new option value.
*/
do_action( 'updated_option', $option, $old_value, $value );
return true;
}
Fonctions utilisées par update_option()
wp_installing()Vérifie ou met Wordpress en mode installation.
wp_cache_get()Retourne le contenu du cache par clé et groupe.
wp_cache_set()Sauvegarde les données pour le cache.
__()Retourne la traduction d'un texte.
sanitize_option()Nettoie divers valeurs d'option basées sur la nature de l'option.
_deprecated_argument()Marque l'argument d'une fonction comme déprécié et informe quand il a été utilisé.
maybe_serialize()Sérialize des données si besoin.
apply_filters()Appel les fonctions qui ont été attaché à un filtre (hook).
do_action()Exécute des fonctions attachées à un hook spécifique.
update_option()Met à jour la valeur d'une option.
add_option()Ajoute une nouvelle option.
wp_load_alloptions()Charge et met en cache toutes les options auto-chargées si disponible ou toutes les options.
wp_protect_special_option()Protège les options natives de WordPress d'être modifiées.
get_option()Retourne une valeur d'option en fonction de son nom.
Hooks utilisés par update_option()
pre_update_option_optionFiltre une option spécifique avant que sa valeur ne soit sérializée (éventuellement) et mise à jour.
pre_update_optionFiltre une option avant que sa valeur ne soit sérializée (éventuellement) et mise à jour.
update_optionSe lance juste avant qu'une valeur d'option ne soit mise à jour.
update_option_optionSe lance après que la valeur d'une option spécifique ait été mise à jour avec succès.
updated_optionSe lance après que la valeur d'une option ait été mise à jour avec succès.
default_option_optionFiltre la valeur par défaut d'une option.
Où est utilisée la fonction update_option()
dans le CMS WordPress
Exemple
update_option( 'default_comment_status', 'closed' );
Sources
Codex WordPress : update_option()
Autres fonctions dans le même fichier : wp-includes/option.php