register_activation_hook()

Définition : register_activation_hook() relie une fonction à l’activation d’un plugin WordPress. Elle permet d’exécuter une initialisation ponctuelle, comme créer des valeurs par défaut ou préparer des règles de réécriture nécessaires.

Terminologie

Terme officiel : register_activation_hook()

Autres appellations : Hook d’activation

À quoi cela sert

Une activation réussie peut préparer les données indispensables au premier usage : options initiales, contrôles de prérequis ou règles de routage. Cette phase n’est pas faite pour produire la sortie HTML des pages publiques.

Comment cela fonctionne

Le premier argument désigne le fichier principal du plugin et le second un callback. WordPress appelle ce callback dans le contexte de l’activation, non à chaque requête. Pour un type de contenu, déclarer d’abord ce type avant de rafraîchir les permaliens.

Dans quel contexte l’utiliser

Utiliser ce hook lorsqu’une action doit se produire au moment précis où un administrateur active l’extension, notamment lors d’une première installation.

Exemple concret

Un plugin doit créer une configuration initiale sans écraser les réglages qui existeraient après réactivation.

Exemple de code commenté

<?php
// Dans le fichier principal d’un plugin.
function atoolpha_demo_activer() {
    add_option( 'atoolpha_demo_limite', 10, '', false );
}
register_activation_hook( __FILE__, 'atoolpha_demo_activer' );

// Fonctionnement normal : l’option est ensuite lue ailleurs.
add_action( 'init', function () {
    $limite = (int) get_option( 'atoolpha_demo_limite', 10 );
    // Exploiter $limite dans un composant réel du plugin.
} );

Explication pas à pas de l’exemple

Le hook de démarrage enregistre l’option seulement si absente. Le hook init lit ensuite la préférence pour le fonctionnement normal. La fonction add_option() préserve une valeur déjà présente, contrairement à une mise à jour forcée.

Résultat attendu

Après activation, l’option de démonstration existe avec la valeur 10 ; les activations futures ne remplacent pas automatiquement un réglage personnalisé.

Précautions et limites

N’utiliser __FILE__ directement que depuis le fichier principal. Une réactivation n’est pas un mécanisme de migration complet ; prévoir des contrôles de version spécifiques lorsque nécessaire.