# wp_get_scheduled_event : lire les détails d’une tâche cron déjà programmée

> Avant de programmer une nouvelle tâche planifiée à chaque activation d'extension, encore faut-il savoir si elle existe déjà. Une fonction native répond exactement à cette question.

- Auteur : WordPress Développement
- Publié le : 2020-03-23
- Mis à jour le : 2020-03-23
- Catégorie : Astuces
- URL : https://www.wpmoderne.fr/tips/wp-get-scheduled-event-details-tache-cron/

## L’essentiel

- Renvoie un objet complet (hook, planification, args) ou false
- Évite d'empiler plusieurs occurrences du même événement
- Se combine avec wp_next_scheduled pour un test rapide

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

> L'essentiel à retenir : Renvoie un objet complet (hook, planification, args) ou false ; Évite d'empiler plusieurs occurrences du même événement ; Se combine avec wp_next_scheduled pour un test rapide

```
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 `interval` de l'objet retourné n'existe que pour les événements récurrents, absent pour un événement ponctuel programmé via `wp_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 que `wp_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.