Une extension qui programme une tâche récurrente à son activation, sans vérifier au préalable si cette tâche existe déjà, finit tôt ou tard par empiler des doublons : chaque réactivation ajoute une nouvelle occurrence du même événement dans la table cron. Le symptôme est classique — un traitement censé s’exécuter une fois par heure se déclenche soudain trois ou quatre fois d’affilée.
La fonction wp_get_scheduled_event() permet de récupérer les informations complètes d’une tâche déjà programmée : son horaire, son intervalle de récurrence et les arguments avec lesquels elle a été enregistrée. Elle offre une vision plus fine que le simple test booléen habituel.
La différence avec wp_next_scheduled
wp_next_scheduled() répond à une question binaire : cet événement, identifié par son nom de hook et ses arguments, est-il déjà dans la file d’attente ? Elle retourne l’horodatage de la prochaine exécution, ou false. C’est suffisant pour éviter un doublon lors de l’activation d’une extension.
wp_get_scheduled_event() va plus loin : elle retourne un objet contenant le hook, l’horodatage, la périodicité (schedule), l’intervalle en secondes et les arguments enregistrés. Utile lorsqu’un écran de diagnostic doit afficher, par exemple, la fréquence exacte à laquelle une tâche a été programmée, sans se contenter de savoir qu’elle existe.
Un exemple d’activation propre
register_activation_hook( __FILE__, 'mon_extension_activation' );
function mon_extension_activation() {
$evenement = wp_get_scheduled_event( 'mon_extension_purge_cache' );
if ( ! $evenement ) {
wp_schedule_event( time(), 'hourly', 'mon_extension_purge_cache' );
}
}
Ce test évite d’appeler wp_schedule_event() à chaque activation ou réactivation de l’extension, un scénario fréquent lors des mises à jour ou des changements de configuration multisite.
Lire la périodicité programmée
L’objet retourné permet aussi de vérifier qu’une tâche tourne bien à l’intervalle attendu, sans dépendre d’une variable stockée séparément en base :
$evenement = wp_get_scheduled_event( 'mon_extension_purge_cache' );
if ( $evenement && 'hourly' !== $evenement->schedule ) {
// La périodicité a changé depuis la dernière activation :
// on reprogramme proprement.
wp_clear_scheduled_hook( 'mon_extension_purge_cache' );
wp_schedule_event( time(), 'hourly', 'mon_extension_purge_cache' );
}
Événements avec arguments
Si une tâche a été programmée avec des arguments (par exemple un identifiant de site sur un réseau multisite), il faut les transmettre également à wp_get_scheduled_event() pour retrouver le bon événement, car WordPress considère chaque combinaison hook et arguments comme un événement distinct.
- Sans argument précisé, la fonction retourne le premier événement trouvé pour ce hook.
- Avec un tableau d’arguments, elle cherche l’événement exact correspondant à cette combinaison.
- Le champ
intervalde l’objet retourné n’existe que pour les événements récurrents, absent pour un événement ponctuel programmé viawp_schedule_single_event().
Où consulter ces informations en pratique
Un écran d’administration interne, réservé aux développeurs, peut afficher ces objets directement pour du diagnostic rapide, plutôt que d’installer une extension tierce dédiée uniquement à l’inspection du cron. Un simple var_export() de l’objet retourné suffit souvent à comprendre pourquoi une tâche ne se déclenche pas au bon moment.
Avant d’écrire une seule ligne de
wp_schedule_event()dans un hook d’activation, vérifiez toujours ce quewp_get_scheduled_event()retourne. C’est la seule façon fiable de savoir si une tâche existe déjà, quelle que soit son origine.
En résumé
Empiler des tâches planifiées identiques est une erreur discrète, difficile à repérer sans lire attentivement la table cron. wp_get_scheduled_event() donne accès à toute l’information nécessaire pour éviter ce piège dès l’activation d’une extension, tout en offrant une base solide pour du diagnostic plus poussé sur des tâches déjà en production.
