API Abilities WP

Quand l'utiliser

Utilisez cette skill quand la tâche implique :

• l'enregistrement d'abilities ou de catégories d'abilities en PHP,
• l'exposition d'abilities aux clients via REST (wp-abilities/v1),
• la consommation d'abilities en JS (notamment @wordpress/abilities),
• le diagnostic des problèmes du type « l'ability n'apparaît pas » / « le client ne voit pas l'ability » / « REST retourne un résultat vide ».

Entrées requises

• Racine du repository (lancez wp-project-triage d'abord si vous ne l'avez pas fait).
• Version(s) WordPress ciblée(s) et indication si c'est du code WP core ou un plugin/thème.
• Où la modification doit résider (plugin vs thème vs mu-plugin).

Procédure

1) Confirmer la disponibilité et les contraintes de version

• S'il s'agit de code WP core, vérifiez signals.isWpCoreCheckout et versions.wordpress.core.
• Si le projet cible WP < 6.9, vous aurez peut-être besoin du plugin/package Abilities API plutôt que de la version core.

2) Trouver l'utilisation existante des Abilities

Recherchez ceux-ci dans le repository :

• wp_register_ability(
• wp_register_ability_category(
• wp_abilities_api_init
• wp_abilities_api_categories_init
• wp-abilities/v1
• @wordpress/abilities

S'il n'en existe aucun, décidez si vous introduisez l'API Abilities à zéro (nouvelles enregistrements + consommation client) ou seulement la consommation.

3) Enregistrer les catégories (optionnel)

Si vous avez besoin d'un regroupement logique, enregistrez une catégorie d'ability dès le départ (voir references/php-registration.md).

4) Enregistrer les abilities (PHP)

Implémentez l'ability en PHP avec :

• un id stable (namespacé),
• label/description,
• category,
• meta:
  • ajoutez readonly: true quand l'ability est informative,
  • définissez show_in_rest: true pour les abilities que vous voulez visibles aux clients.

Utilisez les hooks d'initialisation documentés pour l'enregistrement de l'API Abilities afin qu'ils se chargent au bon moment (voir references/php-registration.md).

5) Confirmer l'exposition REST

• Vérifiez que les endpoints REST existent et retournent les résultats attendus (voir references/rest-api.md).
• Si le client n'arrive toujours pas à voir l'ability, confirmez que meta.show_in_rest est activé et que vous interrogez le bon endpoint.

6) Consommer depuis JS (si nécessaire)

• Privilégiez les API @wordpress/abilities pour l'accès côté client et les vérifications.
• Assurez-vous que l'outillage de build inclut la dépendance et que le pipeline de build du projet la regroupe.

Vérification

• wp-project-triage indique signals.usesAbilitiesApi: true après votre modification (le cas échéant).
• Vérification REST (dans un environnement WP) : les endpoints sous wp-abilities/v1 retournent votre ability et catégorie selon les attentes.
• Si le repository a des tests, ajoutez/mettez à jour la couverture près de :
  • PHP : enregistrement d'ability et exposition des meta
  • JS : consommation d'ability et gating de l'interface

Modes de défaillance / débogage

• L'ability n'apparaît jamais :
  • le code d'enregistrement ne s'exécute pas (mauvais hook / fichier non chargé),
  • meta.show_in_rest manquant,
  • incohérence de catégorie/ID.
• REST affiche l'ability mais JS ne le fait pas :
  • mauvaise base/namespace REST,
  • dépendance JS non regroupée,
  • mise en cache (cache d'objet/page) masquant les modifications.

Escalade

• Si vous êtes incertain quant au support de la version, confirmez les versions WP core cibles et si l'API Abilities est attendue du core ou en tant que plugin.
• Pour les détails canoniques, consultez :
  • references/rest-api.md
  • references/php-registration.md