Documentation · Documentation développeur

Normes de codage

Cette page décrit les conventions qu'une contribution à l'extension doit suivre, à un niveau qui peut être publié en toute sécurité. Les noms de classes internes, les constantes internes, les identifiants de capacités et les conventions de clés d'option sont des détails d'implémentation et ne sont pas publiés ici.

Quand utiliser ce document

Utilisez ce document lorsque vous :

  • Êtes sur le point d'ajouter du PHP, du JavaScript, du CSS, des modèles ou des chaînes traduisibles à une contribution.
  • Examinez une pull request et avez besoin d'une référence pour savoir ce que signifie « cohérent avec la base de code ».
  • Étendez l'extension à partir d'une autre extension ou d'un thème et souhaitez que votre propre code s'intègre de manière native.

PHP

  • Niveau de langue. Ciblez la version PHP déclarée dans l'en-tête de l'extension comme version minimale. Évitez les fonctionnalités qui n'y sont pas disponibles.
  • Déclarations de type. Utilisez des déclarations de type scalaire et de retour sur les nouvelles méthodes, en accord avec le code environnant.
  • Style WordPress. Suivez les normes de codage PHP de WordPress (tabulations pour l'indentation, espaces à l'intérieur des parenthèses, conditions Yoda là où la base de code les utilise déjà, snakecase pour les fonctions et les méthodes, TitleCaseWithUnderscores pour les noms de classes).
  • Une seule classe par fichier. Chaque fichier PHP contient une seule classe. Les noms de fichiers correspondent aux noms de classes sous forme de minuscules séparées par des tirets, conformément aux conventions déjà présentes dans la base de code.
  • Pas de nouvelles variables globales. Privilégiez les constantes de classe et l'injection de dépendances plutôt que des variables globales dispersées.

Intégration WordPress

  • Vérifications des capacités d'abord. Chaque action privilégiée doit vérifier la capacité appropriée avant d'effectuer tout travail.
  • Vérifications de nonce pour les formulaires et l'AJAX d'administration. Utilisez les API de nonce standard de WordPress (check_admin_referer, check_ajax_referer, wp_verify_nonce) pour tout point de terminaison modifiant l'état.
  • Assainissement et échappement. Assainissez les entrées et échappez les sorties en utilisant les API WordPress appropriées pour le type et le contexte de sortie. Voir Sanitization And Escaping.
  • i18n. Enveloppez les chaînes destinées aux utilisateurs avec le domaine de texte de l'extension. Voir Internationalization For Developers.
  • Journalisation. Utilisez le journal partagé de l'extension plutôt que d'appeler directement le error_log de PHP depuis le code d'une nouvelle fonctionnalité.

JavaScript et CSS

  • L'extension n'utilise pas de pipeline de build JavaScript ; les ressources sont livrées sous forme de fichiers bruts.
  • Gardez le JavaScript frontal sans dépendances et progressif ; l'extension doit continuer à fonctionner dans les navigateurs qui bloquent les scripts tiers.
  • Préfixez les nouvelles classes CSS de manière cohérente avec les conventions frontales et d'administration existantes pour éviter les collisions avec les thèmes.

Tests

  • Les nouveaux changements de comportement doivent être couverts par des tests là où ils peuvent raisonnablement être exercés par des tests unitaires.
  • Nommez les nouvelles classes de test d'après la classe ou le comportement testé avec un suffixe Test, conformément aux tests existants.
  • Voir le Guide de test pour le flux de travail de test de haut niveau.

Documentation

  • Mettez à jour les pages concernées sous docs/en/ chaque fois qu'une contribution modifie un comportement observable publiquement.
  • Gardez la documentation publique sécurisée ; n'ajoutez pas de noms de classes internes, de clés d'option, de noms de routes REST/AJAX ou d'identifiants de capacités/nonces à l'ensemble de la documentation publique.

Avis de documentation publique. Cette page fournit uniquement un aperçu de haut niveau de l'intégration. Les détails d'implémentation interne, les API privées, les détails de stockage et l'infrastructure de publication sensible à la sécurité sont gérés séparément et ne font pas partie de la documentation publique.