add_option()

Définition : add_option() ajoute une option WordPress seulement si son nom n’existe pas déjà. Elle convient pour initialiser des paramètres par défaut d’une extension sans écraser les valeurs enregistrées par l’administrateur.

Terminologie

Terme officiel : add_option()

Autres appellations : Ajout initial d’option

À quoi cela sert

Cette fonction facilite la première configuration d’un plugin tout en respectant les préférences déjà présentes. Elle permet également de maîtriser le chargement automatique de certaines options utilisées rarement sur le site.

Comment cela fonctionne

La fonction tente d’insérer une option nommée avec une valeur et un comportement d’autoload. Elle retourne false si l’option existe déjà ou si l’ajout échoue. Contrairement à update_option(), elle n’est pas conçue pour remplacer une valeur existante.

Dans quel contexte l’utiliser

À utiliser lors de la phase d’activation d’un plugin pour créer ses paramètres initiaux, puis gérer leurs évolutions par des procédures dédiées.

Exemple concret

Un plugin utilise une limite d’éléments par défaut égale à 12, mais ne doit jamais la réinitialiser après que l’administrateur l’a modifiée.

Exemple de code commenté

<?php
// Dans le fichier principal de l’extension.
function atoolpha_demo_premiere_activation() {
    add_option(
        'atoolpha_demo_elements',
        12,
        '',
        false // Ne pas charger automatiquement à chaque requête.
    );
}
register_activation_hook(
    __FILE__,
    'atoolpha_demo_premiere_activation'
);

Explication pas à pas de l’exemple

La routine d’activation appelle add_option() avec un nom préfixé. Si l’option manque, elle est créée avec 12 ; si elle existe, la valeur enregistrée reste inchangée. Le dernier argument permet de limiter son chargement automatique.

Résultat attendu

La première activation initialise la préférence ; une désactivation puis réactivation ne remet pas automatiquement le paramètre à 12.

Précautions et limites

Éviter d’écrire trop d’options autoloadées et de stocker des volumes volumineux dans les réglages. La gestion de migrations de schéma doit être distincte d’un ajout initial.