Relier Sentry à l’Abilities API de WordPress 6.9 pour diagnostiquer un thème

wp abilities list --format=json — cette commande retourne la liste des capacités enregistrées sur un site. Elle ne fonctionne pas encore nativement : à ce stade, l’Abilities API n’existe que sous forme de plugin d’extension officiel, en préparation d’une fusion annoncée dans le cœur de WordPress avec la future version 6.9. Ce plugin suffit déjà pour tester en conditions réelles comment un site peut exposer des actions et des informations à des systèmes externes, y compris à des outils de suivi d’erreurs comme Sentry, déjà utilisé pour surveiller le PHP applicatif d’un thème d’agence.

Ce tutoriel construit une capacité de diagnostic dédiée au thème via ce plugin d’extension, puis la relie à Sentry pour centraliser la remontée d’erreurs. Il ne traite ni le protocole MCP en tant que tel, ni les autres capacités prévues nativement pour WordPress 6.9 : uniquement cette capacité de diagnostic spécifique, testée en amont de la fusion dans le cœur.

Pourquoi passer par l’Abilities API plutôt qu’un simple hook

Sans l’Abilities API, exposer un état de santé de thème vers un système externe demande de bricoler un endpoint REST personnalisé, avec sa propre authentification, sa propre structure de réponse, et souvent sans convention partagée d’un projet à l’autre. L’Abilities API standardise cette exposition : chaque capacité déclare un nom, une description, un schéma d’entrée et de sortie, et devient automatiquement découvrable par tout système qui interroge cette API — y compris un futur serveur MCP, sans travail supplémentaire côté thème.

Déclarer la capacité de diagnostic

L’enregistrement d’une capacité se fait via la fonction wp_register_ability(), fournie par le plugin d’extension Abilities API en attendant son intégration prévue dans le cœur. La capacité de diagnostic du thème retourne un instantané de son état : version active, nombre de patterns enregistrés, présence ou non d’un cache objet persistant, et dernière erreur PHP capturée localement.

add_action( 'abilities_api_init', function () {
    wp_register_ability( 'agence-theme/diagnostic', array(
        'label'       => 'Diagnostic du thème',
        'description' => 'Retourne un instantané de l\'état de santé du thème actif',
        'output_schema' => array(
            'type' => 'object',
            'properties' => array(
                'version_theme'      => array( 'type' => 'string' ),
                'cache_objet_actif'  => array( 'type' => 'boolean' ),
                'nombre_patterns'    => array( 'type' => 'integer' ),
                'derniere_erreur'    => array( 'type' => 'string' ),
            ),
        ),
        'execute_callback' => 'agence_theme_executer_diagnostic',
    ) );
} );

function agence_theme_executer_diagnostic() {
    $theme = wp_get_theme();

    return array(
        'version_theme'     => $theme->get( 'Version' ),
        'cache_objet_actif' => wp_using_ext_object_cache(),
        'nombre_patterns'   => count( WP_Block_Patterns_Registry::get_instance()->get_all_registered() ),
        'derniere_erreur'   => get_transient( 'agence_theme_derniere_erreur' ) ?: 'aucune',
    );
}

Capturer les erreurs PHP du thème dans un transient

Pour que le champ derniere_erreur ait un sens, le thème doit déjà capturer ses propres erreurs. Un gestionnaire simple, accroché à wp_die_handler ou à une fonction de journalisation interne existante, écrit l’erreur la plus récente dans un transient à courte durée de vie.

function agence_theme_enregistrer_erreur( $message ) {
    set_transient( 'agence_theme_derniere_erreur', $message, HOUR_IN_SECONDS );
}

Relier cette capacité à Sentry

Sentry ne consomme pas nativement l’Abilities API — la connexion se fait via un petit script planifié, exécuté par une tâche cron WordPress, qui interroge la capacité localement puis transmet les données à Sentry via son API d’événements personnalisés.

add_action( 'agence_theme_verification_horaire', function () {
    $diagnostic = wp_execute_ability( 'agence-theme/diagnostic' );

    if ( 'aucune' !== $diagnostic['derniere_erreur'] ) {
        $client = \Sentry\SentrySdk::getCurrentHub();
        $client->captureMessage(
            sprintf(
                'Diagnostic thème : %s (cache: %s, patterns: %d)',
                $diagnostic['derniere_erreur'],
                $diagnostic['cache_objet_actif'] ? 'actif' : 'inactif',
                $diagnostic['nombre_patterns']
            )
        );
    }
} );

if ( ! wp_next_scheduled( 'agence_theme_verification_horaire' ) ) {
    wp_schedule_event( time(), 'hourly', 'agence_theme_verification_horaire' );
}

Ce script ne remonte un événement Sentry que lorsqu’une erreur a réellement été capturée depuis la dernière vérification, évitant de saturer le tableau de bord Sentry avec des événements de routine sans valeur diagnostique.

Vérifier le résultat côté Sentry

1. Provoquer volontairement une erreur PHP contrôlée dans un environnement de test
2. Confirmer sa capture dans le transient via wp abilities call agence-theme/diagnostic en ligne de commande
3. Attendre le prochain déclenchement de la tâche planifiée, ou la forcer via wp cron event run agence_theme_verification_horaire
4. Vérifier l’apparition de l’événement correspondant dans le tableau de bord Sentry, avec le contexte structuré attendu

Ne remontez jamais l’intégralité d’une trace de pile PHP brute vers un outil externe via une capacité publique de l’Abilities API. Filtrez et structurez systématiquement ce qui sort, pour éviter une fuite accidentelle d’informations sensibles sur l’infrastructure du site.

En résumé

L’Abilities API de WordPress 6.9 offre un cadre structuré pour exposer un état de santé de thème vers un outil de suivi comme Sentry, sans bricoler un endpoint REST maison. Une seule capacité bien conçue, interrogée à intervalle régulier par une tâche planifiée, suffit à centraliser ce suivi — à condition de rester rigoureux sur ce qui transite réellement vers l’extérieur.