Sujets
Développer une extension WordPress
Bienvenue sur la version française du guide à destination des développeuses et développeurs d’extensions WordPress. Que vous soyez en train d’écrire votre première ou votre cinquantième extension, il est toujours de bon ton de parcourir ce guide avant de se lancer.
Ce guide couvre un grand nombre de sujets, de la définition des en-têtes de votre extension aux bonnes pratiques de sécurité, en passant par les outils à votre disposition pour créer votre extension.
Pourquoi développons-nous des extensions WordPress ?
Une des règles les plus importantes dans le développement pour ce CMS, c’est qu’il ne faut jamais toucher au cœur de WordPress !
Il ne faut jamais modifier le moindre fichier appartenant au cœur de WP pour ajouter une fonctionnalité à votre site. En effet, lors de chaque mise à jour, l’ensemble des fichiers du cœur WP sont écrasés par la nouvelle version. C’est pour cela que toute fonctionnalité que vous souhaitez ajouter devrait être développée sous la forme d’une extension.
Qu’est-ce qu’une extension WordPress ?
Une extension est un code source écrit dans le but d’étendre les fonctionnalités natives de WordPress. Les extensions WordPress sont créées à partir du langage de programmation PHP et peuvent contenir des ressources complémentaires comme des fichiers CSS, JavaScript et tous types de médias.
En créant votre propre extension, vous étendez WordPress (d’où le terme « extension » 😉). Cela signifie que vous construisez des fonctionnalités nouvelles qui vont s’ajouter à ce que WordPress propose par défaut. Par exemple, vous pourriez créer une extension permettant d’afficher un lien vers les 10 articles les plus récents de votre site. Ou alors, vous pourriez écrire une extension permettant de créer un système complet de ticket de support, comprenant des types de publications personnalisés, des notifications e-mail, et même une interface publique pour votre gestionnaire de ticket. Les possibilités sont infinies et dans tous les cas, cela passera par la création d’une extension !
La plupart des extensions contiennent de nombreux fichiers, mais au final, une extension ne nécessite rien de plus qu’un fichier PHP principal avec un en-tête comprenant un DocBlock.
Hello Dolly, l’une des toutes premières extensions à avoir été créée, ne contient que 100 lignes de code. Hello Dolly affiche les paroles d’une chanson américaine bien connue de Louis Armstrong (en anglais) sur l’administration WP. Un peu de CSS est ajouté pour la forme. Hello Dolly a pour rôle de montrer comment une extension peut étendre les fonctionnalités de WordPress avec un exemple ultra basique et facile à comprendre.
En tant qu’auteur ou autrice d’extension WordPress.org, vous avez de votre côté une belle opportunité de bâtir quelque chose qui peut-être sera installé, utilisé et aimé par des milliers d’utilisateurs et utilisatrices de WordPress. Tout ce dont vous avez besoin, c’est de transformer vos idées en code source, puis de le mettre à disposition du public. Ce guide est là pour vous aider à y arriver.
Déposer son extension sur le répertoire WordPress.org
WordPress.org vous propose d’héberger gratuitement votre extension sur un répertoire ouvert à toutes les personnes qui utilisent WordPress. Toutes les extensions hébergées sur WordPress.org disposent des avantages suivants :
- Un suivi des statistiques d’usage.
- Un forum de support dédié à l’extension, où vous pourrez venir en aide à vos utilisateurs et utilisatrices.
- Un système d’évaluation permettant à vos utilisateurs et utilisatrices de vous faire part de leur avis.
Prérequis
- Toutes les extensions WordPress, qu’elles soient hébergées sur le répertoire officiel WordPress.org ou non, doivent être compatibles avec la licence publique générale GNU-GPL, dans sa version 2 ou plus. Si aucune licence n’est précisée, alors la licence de l’extension sera automatiquement « GPL version 2 ou plus ».
- Le répertoire officiel n’est pas adapté pour les extensions premium (avec paiement de licence). Les extensions WordPress du répertoire officiel sont toutes téléchargeables, utilisables et maintenables gratuitement et sans contrepartie financière.
- Le répertoire Subversion fourni par WordPress.org ne doit être utilisé que pour des extensions fonctionnelles, et non pour héberger des travaux en cours de développement.
- L’affichage de liens de type « propulsé par [nom de votre extension ou de votre société] », la publicité, ou les appels à des services externes sont interdits, à moins d’être entièrement documentés et de demander le consentement explicite des utilisateurs et utilisatrices de l’extension au préalable.
- L’extension ainsi que son auteur ou son autrice ne doivent rien faire d’illégal ni de moralement ou éthiquement problématique. L’usage du spam ou du harcèlement (qu’il soit publicitaire ou autre) est prohibé.
Toutes les extensions WordPress ainsi que l’activité des auteurs et autrices d’extensions doivent être conformes aux lignes de conduite détaillées des extensions WordPress.org.
Utiliser Subversion (SVN) pour versionner son extension WordPress
SVN (ou Subversion) est un système de contrôle de version similaire à Git. Il peut être utilisé en ligne de commande ou via de nombreuses interfaces GUI telles que Tortoise SVN (en anglais) ou SmartSVN (en anglais).
Cette page n’a pas l’ambition de fournir un guide complet sur l’utilisation de SVN mais plutôt une première approche rapide et efficace sur l’utilisation de SVN pour publier son extension sur WordPress.org. Pour une documentation complète, consultez le livre d’utilisation dédié de SVN (cela n’est pas obligatoire si vous voulez juste publier votre code sur le répertoire WordPress.org).
Sur cette page, nous décrirons les manipulations de base nécessaires à maîtriser pour publier une extension sur WordPress.org.
Attention : le répertoire des extensions WordPress.org et le dépôt SVN associé sont des répertoires contenant des versions finales de vos extensions.
Contrairement aux habitudes que vous pouvez avoir avec GitHub, il ne faut pas utiliser votre répertoire WordPress.org (cela s’applique à toutes les branches du répertoire) pour le développement de l’extension.
Ne « committez » sur votre dépôt SVN que du code finalisé et prêt à être déployé.
Vue d’ensemble de Subversion
Tous vos fichiers seront stockés de manière centralisée dans le dépôt SVN situé sur nos serveurs. À partir de ce dépôt, n’importe qui peut extraire une copie de vos fichiers d’extension sur son ordinateur local, mais, en tant qu’auteur ou autrice d’extension, vous êtes l’unique personne qui a le droit de vous y connecter.
Cela signifie que vous pouvez apporter des modifications aux fichiers, ajouter de nouveaux fichiers ou supprimer des fichiers existants puis mettre en place ces modifications sur le serveur centralisé WordPress.org. C’est ce processus qui permet de mettre à jour les fichiers du dépôt et en même temps les informations affichées dans le répertoire des extensions WordPress.org.
Subversion garde la trace de tous ces changements afin que vous puissiez revenir en arrière et consulter les anciennes versions ou révisions plus tard si jamais vous en avez besoin. En plus de mémoriser chaque révision individuellement, vous pouvez demander à Subversion de marquer certaines révisions du référentiel pour pouvoir plus facilement y faire référence par la suite.
Ce système de « tags » est idéal pour étiqueter différentes versions de votre extension et reste la seule méthode entièrement prise en charge pour vous garantir que les bonnes versions de votre extension sont mises à jour sur WordPress.org.
Votre compte Subversion
Votre compte SVN utilisera le même identifiant (et non l’e-mail) du compte que vous avez utilisé lorsque vous avez proposé l’extension sur le répertoire WordPress.org. Il s’agit de l’identifiant que vous utilisez également pour les forums WordPress.
N’oubliez pas que les majuscules sont importantes – si votre identifiant est JeanneDupont, vous devez utiliser les majuscules J et D, sinon SVN n’arrivera pas à se connecter. Vous pouvez voir l’identifiant exact de votre compte à l’adresse https://profiles.wordpress.org/me/profile/edit/group/1/.
Si vous devez réinitialiser votre mot de passe, rendez-vous sur login.wordpress.org.
Les dossiers SVN
Il existe trois dossiers créés par défaut dans tous les dépôts SVN :
Le dossier /assets/
Ce dossier est utilisé pour y placer les bannières et icônes de votre extension, ainsi que les captures d’écrans que vous souhaitez présenter sur la page de votre extension sur WordPress.org.
Certaines extensions plus anciennes dans le répertoire peuvent avoir des fichiers de captures d’écrans dans /trunk/ à la place, mais ce n’est pas recommandé. Toutes les nouvelles extensions doivent placer leurs captures d’écran dans /assets/. Cela permet de réduire la taille des fichiers des extensions, car il n’est pas nécessaire d’envoyer des captures d’écrans aux installations WordPress utilisant l’extension elle-même.
Le dossier /trunk/
Ce dossier est utilisé pour stocker la version courante de votre extension : il s’agit du dossier qui contient les derniers développements à jour de votre extension.
Ne placez jamais le fichier principal de votre extension dans un sous-dossier sur trunk, comme /trunk/mon-extension/mon-extension.php car cela casserait le système de téléchargement de l’extension. Vous pouvez utiliser des sous-dossiers pour les autres fichiers utilisés par votre extension.
Le dossier /trunk/ peut être considéré comme la version la plus à jour de votre code, mais ce n’est pas nécessairement le dernier code stable. Ce dossier est utilisé pour indiquer la version de développement. Idéalement, le code situé sur trunk devrait toujours être fonctionnel, mais il peut être bogué de temps en temps car ce n’est pas forcément la version « stable » et publique de votre extension. Pour les extensions vraiment très simples, vous pouvez si vous le souhaitez n’utiliser que le dossier /trunk/, sans utiliser le dossier /tags/. Mais ce n’est recommandé que pour les très petites extensions qui ne contiennent que quelques lignes de code.
Même si vous effectuez votre travail de développement ailleurs (comme un référentiel git), nous vous recommandons de garder le dossier trunk à jour avec votre code pour faciliter les comparaisons de code entre votre copie locale (ou sur GitHub par exemple) et SVN.
Le dossier /tags/
Ce dossier est utilisé afin de stocker les différentes versions de votre extension. C’est ce dossier qui fournit les paquets de fichiers qui seront téléchargés par les utilisateurs et utilisatrices de votre extension.
Pour chaque nouvelle version de votre extension, vous créerez un nouveau dossier au sein du dossier /tags/, qui contiendra le code de votre nouvelle version. Pour vous assurer que vos utilisateurs obtiennent le bon code lorsqu’ils téléchargent ou mettent à jour l’extension, il est important d’être rigoureux et logique dans le numérotage des versions de votre extension.
Par exemple, la version 1.0 de l’extension sera disponible dans le sous-dossier /tags/1.0, la version 1.1 de l’extension sera disponible dans le sous-dossier /tags/1.1, et ainsi de suite.
Nous encourageons fortement l’utilisation du versionnement sémantique. Oui, WordPress lui-même ne l’utilise pas de façon tout à fait rigoureuse, mais c’est une décision qui a été prise il y a plus de 18 ans, et il est difficile de revenir sur l’approche hybride (majeure.mineure.correctif) utilisée par le cœur du CMS depuis ses débuts.
L’ancien dossier /branches/ (déprécié)
Le dossier /branches/ n’est dorénavant plus créé par défaut lors de la création de votre dépôt SVN. Il a été supprimé car il était très peu utilisé.
Dépôt et mise à jour de votre extension via SVN
Déposer une extension sur WordPress.org
Pour mettre en ligne votre extension sur WordPress.org, vous devez ajouter les fichiers que vous avez sur votre ordinateur sur votre nouveau dépôt SVN.
Créez d’abord un répertoire local sur votre machine pour héberger une copie du dépôt SVN :
$ mkdir mon-dossier-local
Ensuite, faites un checkout de votre dépôt SVN afin d’initialiser le versionnement de votre extension sur votre ordinateur :
$ svn co https://plugins.svn.wordpress.org/mon-extension mon-dossier-local
> A mon-dossier-local/trunk
> A mon-dossier-local/branches
> A mon-dossier-local/tags
> Checked out revision 11325.
Ci-dessus, les lignes commençant par « > » correspondent aux réponses du serveur à votre ligne de commande.
Dans notre exemple, Subversion a ajouté (« A » pour « add ») tous les dossiers existant sur le dépôt SVN WordPress.org à votre dossier local.
Vous devez maintenant vous positionner à l’intérieur du dossier de votre extension :
$ cd mon-dossier-local
Vous pouvez maintenant ajouter vos fichiers dans le répertoire /trunk/ de votre dossier local à l’aide d’un copier/coller avec l’explorateur de fichiers de votre ordinateur, ou via la ligne de commande de votre terminal. Faites comme vous préférez 🙂
Ne placez pas le fichier principal de votre extension dans un sous-dossier de /trunk/, comme /trunk/mon-extension/mon-extension.php car cela casserait le téléchargement de votre extension sur le dépôt WordPress.org. Vous pouvez utiliser des sous-dossiers pour les autres fichiers de votre extension.
Une fois que vos fichiers sont dans le dossier /trunk/ sur votre ordinateur, vous devez informer Subversion que vous souhaitez ajouter ces nouveaux fichiers sur le dépôt WordPress.org :
$ svn add trunk/*
> A trunk/mon-extension.php
> A trunk/readme.txt
Après avoir ajouté vos fichiers, vous allez « committer » les modifications sur le dépôt WordPress.org :
$ svn ci -m 'Ajout de la première version de mon extension'
> Adding trunk/mon-extension.php
> Adding trunk/readme.txt
> Transmitting file data .
> Committed revision 11326.
Comme dans l’exemple ci-dessus, il est nécessaire d’inclure un message détaillé pour tous les « commits ».
Si le « commit » échoue à cause d’une interdiction d’accès et que vous savez que vous avez un accès au dépôt de l’extension, ajoutez votre identifiant et votre mot de passe à la commande :
$ svn ci -m 'Ajout de la première version de mon extension' --username votre_identifiant --password votre_mot_de_passe
Souvenez-vous : l’identifiant est sensible à la casse.
Mettre à jour une extension existante avec SVN
Une fois que votre extension est sur le répertoire WordPress.org, vous devrez probablement modifier le code à un moment donné.
Allez d’abord dans votre copie locale du dépôt SVN et assurez-vous qu’il est à jour :
$ cd mon-dossier-local/
mon-dossier-local/ $ svn up
> At revision 11326.
Dans l’exemple ci-dessus, nous sommes à jour. S’il y avait eu des modifications dans le dépôt WordPress.org, elles auraient été téléchargées et fusionnées dans votre copie locale.
Vous pouvez maintenant modifier le fichier en utilisant l’éditeur de votre choix.
Si vous n’utilisez pas d’interface graphique SVN (comme Subversion ou Coda), vous pouvez toujours vérifier et voir ce qui est différent entre votre copie locale et le dépôt WordPress.org après avoir apporté des modifications. Tout d’abord, nous vérifions l’état de la copie locale :
mon-dossier-local/ $ svn stat
> M trunk/mon-extension.php
Cela nous indique que notre fichier trunk/mon-extension.php est différent de la copie que nous avons récupérée à partir du dépôt WordPress.org (« M » pour « modifié »).
Voyons ce qui a exactement changé dans ce fichier, afin que nous puissions nous assurer que les choses se présentent bien :
mon-dossier-local/ $ svn diff
> * Ici, vous obtiendrez généralement la même chose que si vous aviez
* fait une commande standard `diff -u` entre votre copie locale et
* la copie originale que vous avez téléchargée.
Si tout semble bon, il est temps d’envoyer ces modifications sur le dépôt WordPress.org :
mon-dossier-local/ $ svn ci -m "Nouvelle fonctionnalité : maintenant on peut faire ceci et cela !"
> Sending trunk/mon-extension.php
> Transmitting file data .
> Committed revision 11327.
Voilà, vous avez mis à jour /trunk/ avec succès sur le dépôt de votre extension sur WordPress.org.
Taguer une nouvelle version
Chaque fois que vous publiez une nouvelle version officielle de votre extension, vous devez « taguer » une copie du code de cette version, car cela :
- permet aux personnes utilisant votre extension de récupérer facilement la dernière (ou une plus ancienne) version ;
- vous permet de suivre plus facilement les modifications ;
- permet au répertoire d’extensions WordPress.org de savoir quelle version de votre extension il doit demander aux gens de télécharger.
Copiez d’abord votre code dans un sous-répertoire du répertoire /tags/. Pour une meilleure compatibilité avec le répertoire d’extensions WordPress.org, le nouveau sous-répertoire doit toujours ressembler à un numéro de version. Par exemple, vous pouvez utiliser quelque chose comme 2.0.1.3. C’est une mauvaise idée d’utiliser autre chose qu’un numéro de version comme nom de tag.
Nous allons utiliser la commande svn cp au lieu de la commande standard cp afin de profiter des fonctionnalités de SVN :
mon-dossier-local/ $ svn cp trunk tags/2.0
> A tags/2.0
Comme toujours, vérifiez les modifications :
mon-dossier-local/ $ svn ci -m "Tag de la version 2.0"
> Adding tags/2.0
> Adding tags/2.0/mon-extension.php
> Adding tags/2.0/readme.txt
> Committed revision 11328.
Lorsque vous « taguez » une nouvelle version, n’oubliez pas de mettre à jour le champ Stable tag dans le fichier readme.txt de la nouvelle version (ainsi que de /trunk/).
Félicitations ! Vous avez mis à jour votre code comme un·e pro !
Notes importantes :
Ne mettez rien sur SVN que vous ne souhaitez pas déployer sur le site de toutes les personnes qui utilisent votre extension. Cela inclut les fichiers vendor, .gitignore et tout le reste.
Vous ne devez également jamais télécharger de fichiers zippés. Comme la plupart des systèmes de versionnement, SVN s’attend à ce que vous téléversiez des fichiers individuels.
Erreurs et avertissements
Lorsque vous visitez les pages des extensions sur le répertoire WordPress.org, vous pouvez parfois tomber sur des alertes ou des avertissements spéciaux. Ceux-ci existent pour aider les visiteurs à comprendre le statut actuel des extensions concernées.
Approved and Pending Data – Extension approuvée et en attente de données
Les extensions qui ont été approuvées mais pour lesquelles aucun code n’a encore été téléversé verront ce message : ceci s’affiche uniquement pour le ou la propriétaire de l’extension et disparaîtra une fois que le code aura été poussé via SVN.
Closed – Extension fermée
Depuis novembre 2017, les extensions fermées affichent la notification suivante :
Ceci est visible par tous les personnes visitant la page de l’extension et indique que cette extension a été fermée. Les extensions fermées après janvier 2018 incluront une date :
Après 60 jours, la notification sera mise à jour automatiquement pour expliquer pourquoi l’extension a été fermée :
Les personnes ayant un accès « commit » sur l’extension verront la note additionnelle suivante :
Les raisons pour lesquelles certaines extensions sont fermées
- Demande de l’auteur ou de l’autrice – la personne qui s’occupe de l’extension a demandé sa fermeture ;
- Violation des lignes de conduite – une violation de l’une des lignes de conduite concernant le répertoire d’extensions ;
- Violation de licence/marque déposée – si utilisation de code non-GPL, ou si les marques déposées sont utilisées à mauvais escient ;
- Fusionné dans le cœur WP – l’extension fait maintenant partie du cœur (réservé aux extension de fonctionnalités du cœur) ;
- Problème de sécurité – un problème de sécurité a été trouvé dans cette extension.
Les détails supplémentaires sur les raisons pour lesquelles une extension est fermée ne sont fournis à personne d’autre en dehors de l’équipe de sécurité de WordPress.org ou des auteurs ou autrices de l’extension, sauf en cas de circonstances extrêmes.
Out of Date – Extension obsolète
Les extensions qui ne prennent pas en charge les 3 dernières versions majeures de WordPress affichent la notification suivante :
Auparavant, ce message alertait les personnes utilisant l’extension que celle-ci n’a pas été mise à jour au cours des 2 dernières années. En 2018, il a été modifié pour s’appuyer sur des données plus pertinentes. Étant donné que le cœur de WordPress est mis à jour avec une nouvelle version majeure environ 2 à 3 fois par an et qu’une extension maintenue doit être testée avec les versions récentes, cet avertissement peut être évité en mettant simplement à jour le fichier readme de l’extension lorsque de nouvelles versions de WordPress sont disponibles.
Les développeuses et développeurs d’extensions reçoivent un e-mail avant chaque nouvelle version majeure de WordPress et sont invité·e·s à mettre à jour leur prise en charge de la nouvelle version en amont. Ils n’ont pas besoin de pousser une nouvelle version pour cela : il suffit de mettre à jour le fichier readme et de modifier la valeur de l’en-tête « Tested up to : » avec la dernière version de WordPress.
Rédigé par Jb Audras
Relu par Loïc Antignac & Sébastien Serre
Dernière mise à jour le 14 octobre 2021