Faire fonctionner GraphQL dans WordPress

Headless WordPress semble être à la mode ces derniers temps, avec de nombreux nouveaux développements qui ont eu lieu au cours des dernières semaines seulement. L'une des raisons de l'explosion de l'activité est la sortie de la version 1.0 de WPGraphQL, un serveur GraphQL pour WordPress.

WPGraphQL fournit une API GraphQL : un moyen de récupérer et de publier des données sur un site Web WordPress. Il nous permet de découpler l'expérience de gestion de notre contenu, qui se fait via WordPress, du rendu du site web, pour lequel nous pouvons utiliser la librairie du framework de notre choix (React, Vue.js, Gatsby, Next.js, ou tout autre).

Jusqu'à récemment, WPGraphQL était le seul serveur GraphQL pour WordPress. Mais maintenant, un autre plugin de ce type est disponible : l'API GraphQL pour WordPress, dont je suis l'auteur.

Ces deux plugins ont le même objectif : fournir une API GraphQL à un site WordPress. Vous vous demandez peut-être : pourquoi un autre plugin alors qu'il y a déjà WPGraphQL ? Ces deux plugins font-ils la même chose ? Ou sont-ils pour des situations différentes?

Permettez-moi de dire ceci d'abord : WPGraphQL fonctionne très bien. Je n'ai pas construit mon plugin à cause d'un problème avec celui-ci.

J'ai construit l'API GraphQL pour WordPress parce que j'avais travaillé sur un moteur pour récupérer efficacement les données , ce qui s'est avéré très approprié pour GraphQL. Alors, je me suis dit : « Pourquoi pas ? », et je l'ai construit. (Et aussi quelques autres raisons.)

Les deux plugins ont des architectures différentes, leur donnant des caractéristiques différentes, ce qui facilite la réalisation de tâches particulières avec l'un ou l'autre plugin.

Dans cet article, je décrirai, de mon propre point de vue mais aussi objectivement que possible, quand WPGraphQL est la voie à suivre et quand l'API GraphQL pour WordPress est un meilleur choix.

Utilisez WPGraphQL si : Utilisation de Gatsby

Si vous créez un site Web à l'aide de Gatsby, vous n'avez qu'un seul choix : WPGraphQL.

La raison en est que seul WPGraphQL possède le plugin source Gatsby pour WordPress. De plus, le créateur de WPGraphQL, Jason Bahl, était employé jusqu'à récemment par Gatsby, nous pouvons donc être pleinement convaincus que ce plugin répondra aux besoins de Gatsby.

Gatsby reçoit toutes les données du site WordPress, et à partir de là, la logique de l'application sera entièrement du côté de Gatsby, pas de WordPress. Par conséquent, aucun ajout à WPGraphQL (tel que les ajouts potentiels des directives @stream ou @defer ) ne ferait une grande différence.

WPGraphQL est déjà aussi bon que Gatsby en a besoin.

Utilisez WPGraphQL si : Utilisation de l'un des nouveaux frameworks sans tête

Comme je l'ai mentionné, il y a eu récemment une vague d'activités dans l'espace sans tête WordPress concernant plusieurs nouveaux frameworks et projets de démarrage, tous basés sur Next.js :

• Colby Fayock a créé Next.js WordPress Starter.
• WebDevStudios a lancé son propre WordPress Starter Next.js.
• WP Engine a créé le Headless WordPress Framework, qui alimente son service pour héberger et déployer des sites Web WordPress sans tête.

Si vous devez utiliser l'un de ces nouveaux frameworks sans tête, vous devrez utiliser WPGraphQL, car ils ont tous été construits sur ce plugin.

C'est un peu dommage : j'aimerais vraiment que l'API GraphQL pour WordPress puisse aussi les alimenter. Mais pour que cela se produise, ces frameworks devraient fonctionner avec GraphQL via une interface , afin que nous puissions échanger des serveurs GraphQL.

J'espère quelque peu que l'un de ces frameworks mettra en place une telle interface. J'ai posé des questions à ce sujet dans le forum de discussion Headless WordPress Framework et on m'a dit que cela pourrait être envisagé. J'ai également demandé dans le forum de discussion Next.js WordPress Starter de WebDevStudios, mais hélas, ma question a été immédiatement supprimée, sans réponse. (Ce n'est pas encourageant, n'est-ce pas ?)

Donc WPGraphQL c'est alors, actuellement et dans un avenir prévisible.

Utilisez l'un ou l'autre (ou aucun) si : Utilisation de Frontity

Frontity est un framework React pour WordPress. Il vous permet de créer une application basée sur React qui est gérée en back-end via WordPress. Même la création d'articles de blog à l'aide de l'éditeur WordPress est prise en charge par défaut.

Frontity gère l'état de l'application, sans divulguer comment les données ont été obtenues. Même s'il est basé sur REST par défaut, vous pouvez également l'alimenter via GraphQL en implémentant le plugin source correspondant.

C'est ainsi que Frontity est intelligent : Le plugin source est une interface pour communiquer avec le fournisseur de données. Actuellement, le seul plugin source disponible est celui de l'API WordPress REST. Mais n'importe qui peut implémenter un plugin source pour l'API WPGraphQL ou GraphQL pour WordPress. (C'est l'approche que je souhaite que les frameworks basés sur Next.js soient répliqués.)

Conclusion : Ni WPGraphQL ni l'API GraphQL n'offrent d'avantages par rapport à l'autre pour travailler avec Frontity, et ils nécessitent tous deux un effort initial pour les brancher.

Utilisez WPGraphQL si : Création d'un site statique

Dans les deux premières sections, la conclusion était la même : utilisez WPGraphQL. Mais ma réponse à cette conclusion était différente : alors qu'avec Gatsby, je n'avais aucun regret, avec Next.js, je me sentais obligé de faire quelque chose à ce sujet.

Pourquoi donc?

La différence est que, alors que Gatsby est purement un générateur de site statique, Next.js peut alimenter à la fois des sites Web statiques et en direct.

J'ai mentionné que WPGraphQL est déjà assez bon pour Gatsby. Cette déclaration peut en fait être élargie : WPGraphQL est déjà assez bon pour tout générateur de site statique . Une fois que le générateur de site statique obtient les données du site Web WordPress, tout est pratiquement réglé avec WordPress.

Même si l'API GraphQL pour WordPress offre des fonctionnalités supplémentaires, cela ne fera probablement pas de différence pour le générateur de site statique.

Par conséquent, parce que WPGraphQL est déjà assez bon et qu'il a complètement mappé le schéma GraphQL (qui est toujours en cours pour l'API GraphQL pour WordPress), alors WPGraphQL est l'option la plus appropriée, maintenant et dans un avenir prévisible.

Utiliser l'API GraphQL si : Utiliser GraphQL dans un site Web en direct (c'est-à-dire non statique)

Maintenant, la situation ci-dessus change si nous voulons que GraphQL récupère les données d'un site Web en direct, par exemple lors de l'alimentation d'une application mobile ou du traçage de données en temps réel sur un site Web (par exemple, pour afficher des analyses) ou en combinant les approches statique et en direct. sur le même site.

Par exemple, supposons que nous ayons créé un blog statique simple à l'aide de l'un des frameworks Next.js et que nous souhaitions autoriser les utilisateurs à ajouter des commentaires aux articles de blog. Comment cette tâche doit-elle être gérée ?

Nous avons deux options : statique et en direct (ou dynamique). Si nous optons pour le statique, les commentaires seront rendus avec le reste du site Web. Ensuite, chaque fois qu'un commentaire est ajouté, nous devons déclencher un webhook pour régénérer et redéployer le site Web.

Cette approche présente quelques inconvénients. Le processus de régénération et de redéploiement peut prendre quelques minutes, pendant lesquelles le nouveau commentaire ne sera pas disponible. De plus, si le site Web reçoit de nombreux commentaires par jour, l'approche statique nécessitera plus de temps de traitement du serveur, ce qui pourrait devenir coûteux (certaines sociétés d'hébergement facturent en fonction du temps du serveur).

Dans cette situation, il serait logique de rendre le site Web de manière statique sans commentaires, puis de récupérer les commentaires d'un site en direct et de les rendre dynamiquement dans le client.

Pour cela, Next.js est recommandé plutôt que Gatsby. Il peut mieux gérer les approches statiques et en direct, y compris la prise en charge de différentes sorties pour les utilisateurs ayant des capacités différentes.

Retour à la discussion sur GraphQL : Pourquoi est-ce que je recommande l'API GraphQL pour WordPress lorsqu'il s'agit de données en direct ? Je le fais parce que le serveur GraphQL peut avoir un impact direct sur l'application, principalement en termes de rapidité et de sécurité .

Pour un site Web purement statique, le site Web WordPress peut rester privé (il peut même vivre sur l'ordinateur portable du développeur), il est donc sûr. Et l'utilisateur n'attendra pas de réponse du serveur, donc la vitesse n'est pas nécessairement d'une importance critique.

Pour un site en direct, cependant, l'API GraphQL sera rendue publique, de sorte que la sécurité des données devient un problème. Nous devons nous assurer qu'aucun acteur malveillant ne puisse y accéder. De plus, l'utilisateur attendra une réponse, la vitesse devient donc un facteur critique.

À cet égard, l'API GraphQL pour WordPress présente quelques avantages par rapport à WPGraphQL .

WPGraphQL implémente des mesures de sécurité, telles que la désactivation de l'introspection par défaut. Mais l'API GraphQL pour WordPress va plus loin, en désactivant le point de terminaison unique par défaut (ainsi que plusieurs autres mesures). Cela est possible car l'API GraphQL pour WordPress propose des requêtes persistantes de manière native.

En ce qui concerne la vitesse, les requêtes persistantes rendent également l'API plus rapide, car la réponse peut ensuite être mise en cache via la mise en cache HTTP sur plusieurs couches, y compris le client, le réseau de diffusion de contenu et le serveur.

Ces raisons rendent l'API GraphQL pour WordPress mieux adaptée à la gestion des sites Web en direct.

Utiliser l'API GraphQL si : exposer différentes données pour différents utilisateurs ou applications

WordPress est un système de gestion de contenu polyvalent, capable de gérer le contenu de plusieurs applications et accessible à différents types d'utilisateurs.

Selon le contexte, nous pourrions avoir besoin de nos API GraphQL pour exposer différentes données, telles que :

• exposer certaines données aux utilisateurs payants mais pas aux utilisateurs non rémunérés,
• exposer certaines données à l'application mobile mais pas au site Web.

Pour exposer différentes données, nous devons fournir différentes versions du schéma GraphQL .

WPGraphQL nous permet de modifier le schéma (par exemple, nous pouvons supprimer un champ enregistré). Mais le processus n'est pas simple : les modifications de schéma doivent être codées, et il n'est pas facile de comprendre qui accède à quoi et où (par exemple, tous les schémas seraient toujours disponibles sous le point de terminaison unique, /graphql ).

En revanche, l'API GraphQL pour WordPress prend en charge nativement ce cas d'utilisation : elle propose des points de terminaison personnalisés, qui peuvent exposer différentes données pour différents contextes, tels que :

• /graphql/mobile-app et /graphql/website ,
• /graphql/pro-users et /graphql/regular-users .

Chaque point de terminaison personnalisé est configuré via des listes de contrôle d'accès, pour fournir un accès utilisateur granulaire champ par champ, ainsi qu'un mode API public et privé pour déterminer si les métadonnées du schéma sont disponibles pour tout le monde ou uniquement pour les utilisateurs autorisés.

Ces fonctionnalités s'intègrent directement à l'éditeur WordPress (c'est-à-dire Gutenberg). Ainsi, la création des différents schémas se fait visuellement, de la même manière que la création d'un article de blog. Cela signifie que tout le monde peut produire des schémas GraphQL personnalisés , pas seulement les développeurs.

L'API GraphQL pour WordPress fournit, je crois, une solution naturelle pour ce cas d'utilisation.

Utiliser l'API GraphQL si : Interagir avec des services externes

GraphQL n'est pas simplement une API pour récupérer et publier des données. Tout aussi important (bien que souvent négligé), il peut également traiter et modifier les données - par exemple, en les transmettant à un service externe, comme l'envoi de texte à une API tierce pour corriger les erreurs de grammaire ou le téléchargement d'une image vers une diffusion de contenu. réseau.

Maintenant, quel est le meilleur moyen pour GraphQL de communiquer avec des services externes ? À mon avis, cela est mieux accompli par le biais de directives, appliquées lors de la création ou de la récupération des données (un peu comme le fonctionnement des filtres WordPress).

Je ne sais pas dans quelle mesure WPGraphQL interagit avec les services externes, car sa documentation ne le mentionne pas et la base de code n'offre pas d'exemple de directive ou de document sur la façon d'en créer une.

En revanche, l'API GraphQL pour WordPress prend en charge de manière robuste les directives . Chaque directive d'une requête n'est exécutée qu'une seule fois au total (par opposition à une fois par champ et/ou objet). Cette capacité permet une communication très efficace avec des API externes et intègre l'API GraphQL dans un cloud de services.

Par exemple, cette requête illustre un appel à l'API Google Translate via une directive @translate , pour traduire les titres et extraits de nombreux articles de l'anglais vers l'espagnol. Tous les champs de tous les messages sont traduits ensemble, en un seul appel.

L'API GraphQL pour WordPress est un choix naturel pour ce cas d'utilisation.

Remarque : En fait, le moteur sur lequel l'API GraphQL pour WordPress est basée, GraphQL by PoP, a été spécialement conçu pour fournir des capacités avancées de manipulation de données. C'est une de ses caractéristiques distinctes. Pour un exemple extrême de ce qu'il peut réaliser, consultez le guide sur "Envoi d'une newsletter localisée, utilisateur par utilisateur".

Utilisez WPGraphQL si : vous voulez une communauté de support

Jason Bahl a fait un superbe travail en ralliant une communauté autour de WPGraphQL. Par conséquent, si vous avez besoin de dépanner votre API GraphQL, vous trouverez probablement quelqu'un qui pourra vous aider.

Dans mon cas, je m'efforce toujours de créer une communauté d'utilisateurs autour de l'API GraphQL pour WordPress, et c'est certainement loin de celle de WPGraphQL.

Utilisez l'API GraphQL si : vous aimez l'innovation

J'appelle l'API GraphQL pour WordPress un serveur GraphQL "avant-gardiste". La raison en est que je parcours souvent la liste des demandes de la spécification GraphQL et que j'en implémente certaines bien à l'avance (en particulier celles pour lesquelles je ressens une certaine affinité ou que je peux prendre en charge avec peu d'effort).

À ce jour, l'API GraphQL pour WordPress prend en charge plusieurs fonctionnalités innovantes (telles que l'exécution de requêtes multiples et l'espacement de noms de schéma), proposées en opt-in, et il en est prévu quelques autres.

Utilisez WPGraphQL si : vous avez besoin d'un schéma complet

WPGraphQL a complètement cartographié le modèle de données WordPress, notamment :

• articles et pages,
• types de messages personnalisés,
• catégories et tags,
• taxonomies personnalisées,
• médias,
• menus,
• réglages,
• utilisateurs,
• commentaires,
• plugins,
• thèmes,
• widgets.

L'API GraphQL pour WordPress cartographie progressivement le modèle de données à chaque nouvelle version. A ce jour, la liste comprend :

• articles et pages,
• types de messages personnalisés,
• catégories et tags,
• taxonomies personnalisées,
• médias,
• menus,
• réglages,
• utilisateurs,
• commentaires.

Donc, si vous avez besoin de récupérer des données à partir d'un plugin, d'un thème ou d'un widget, actuellement seul WPGraphQL fait le travail.

Utilisez WPGraphQL si : vous avez besoin d'extensions

WPGraphQL propose des extensions pour de nombreux plugins, notamment Advanced Custom Fields, WooCommerce, Yoast, Gravity Forms.

L'API GraphQL pour WordPress propose une extension pour Events Manager, et elle continuera d'en ajouter après la sortie de la version 1.0 du plugin.

Utilisez l'un ou l'autre si : création de blocs pour l'éditeur WordPress

WPGraphQL et l'API GraphQL pour WordPress travaillent actuellement sur l'intégration de GraphQL avec Gutenberg.

Jason Bahl a décrit trois approches par lesquelles cette intégration peut avoir lieu. Cependant, comme ils ont tous des problèmes, il préconise l'introduction d'un registre côté serveur dans WordPress, afin de permettre l'identification des différents blocs Gutenberg pour le schéma GraphQL.

L'API GraphQL pour WordPress a également une approche d'intégration avec Gutenberg, basée sur la stratégie "créer une fois, publier partout". Il extrait les données de bloc du contenu stocké et utilise un seul type de Block pour représenter tous les blocs. Cette approche pourrait éviter le recours au registre côté serveur proposé.

La solution de WPGraphQL peut être considérée comme provisoire, car elle dépendra de l'acceptation par la communauté de l'utilisation d'un registre côté serveur, et nous ne savons pas si ou quand cela se produira.

Pour l'API GraphQL pour WordPress, la solution dépendra entièrement d'elle-même, et c'est en effet déjà un travail en cours.

Parce qu'il a plus de chances de produire une solution de travail bientôt, je serais enclin à recommander l'API GraphQL pour WordPress . Cependant, attendons que la solution soit entièrement mise en œuvre (dans quelques semaines, selon le plan) pour nous assurer qu'elle fonctionne comme prévu, puis je mettrai à jour ma recommandation.

Utiliser l'API GraphQL si : Distribution de blocs via un plugin

Je me suis rendu compte que peu de plugins (le cas échéant) semblent utiliser GraphQL dans WordPress.

Ne vous méprenez pas : WPGraphQL a dépassé les 10 000 installations. Mais je crois que ce sont principalement des installations pour alimenter Gatsby (afin d'exécuter Gatsby) ou pour alimenter Next.js (afin d'exécuter l'un des frameworks sans tête).

De même, WPGraphQL a de nombreuses extensions, comme je l'ai décrit plus tôt. Mais ces extensions ne sont que cela : des extensions. Ce ne sont pas des plugins autonomes.

Par exemple, l'extension WPGraphQL pour WooCommerce dépend à la fois des plugins WPGraphQL et WooCommerce. Si l'un d'eux n'est pas installé, l'extension ne fonctionnera pas, et ce n'est pas grave. Mais WooCommerce n'a pas le choix de s'appuyer sur WPGraphQL pour fonctionner ; par conséquent, il n'y aura pas de GraphQL dans le plugin WooCommerce.

Je crois comprendre qu'il n'y a pas de plugins qui utilisent GraphQL pour exécuter des fonctionnalités pour WordPress lui-même ou, plus précisément, pour alimenter leurs blocs Gutenberg.

La raison est simple : ni WPGraphQL ni l'API GraphQL pour WordPress ne font partie du noyau de WordPress. Ainsi, il n'est pas possible de s'appuyer sur GraphQL de la même manière que les plugins peuvent s'appuyer sur l'API REST de WordPress. Par conséquent, les plugins qui implémentent les blocs Gutenberg ne peuvent utiliser REST que pour récupérer les données de leurs blocs, pas GraphQL.

Apparemment, la solution consiste à attendre qu'une solution GraphQL (très probablement WPGraphQL) soit ajoutée au cœur de WordPress. Mais qui sait combien de temps cela prendra ? Six mois? Une année? Deux ans? Plus long?

Nous savons que WPGraphQL est envisagé pour le cœur de WordPress parce que Matt Mullenweg y a fait allusion. Mais tant de choses doivent se produire avant cela : faire passer la version minimale de PHP à 7.1 (requise à la fois par WPGraphQL et l'API GraphQL pour WordPress), ainsi qu'avoir un découplage, une compréhension et une feuille de route clairs pour les fonctionnalités que GraphQL alimentera.

(L'édition complète du site, actuellement en cours de développement, est basée sur REST. Qu'en est-il de la prochaine fonctionnalité majeure, les blocs multilingues, qui sera abordée dans la phase 4 de Gutenberg ? Si ce n'est pas cela, alors de quelle fonctionnalité s'agira-t-il ?)

Après avoir expliqué le problème, considérons une solution potentielle - une solution qui n'a pas besoin d'attendre !

Il y a quelques jours, j'ai eu une autre réalisation : à partir de la base de code de l'API GraphQL pour WordPress, je peux produire une version plus petite, contenant uniquement le moteur GraphQL et rien d'autre (pas d'interface utilisateur, pas de points de terminaison personnalisés, pas de mise en cache HTTP, pas de contrôle d'accès, non rien). Et cette version peut être distribuée en tant que dépendance Composer, afin que les plugins puissent l'installer pour alimenter leurs propres blocs.

La clé de cette approche est que ce composant doit être d'une utilisation spécifique pour le plugin, ne pas être partagé avec quelqu'un d'autre. Sinon, deux plugins référençant tous les deux ce composant pourraient modifier le schéma de telle manière qu'ils se substituent l'un à l'autre.

Heureusement, j'ai récemment résolu la portée de l'API GraphQL pour WordPress. Donc, je sais que je suis en mesure de l'étendre pleinement, en produisant une version qui n'entrera en conflit avec aucun autre code sur le site Web.

Cela signifie que cela fonctionnera pour n'importe quelle combinaison d'événements :

• Si le plugin contenant le composant est le seul à l'utiliser ;
• Si l'API GraphQL pour WordPress est également installée sur le même site Web ;
• Si un autre plugin qui intègre également ce composant est installé sur le site Web ;
• Si deux plugins qui embarquent le composant font référence à la même version du composant ou à des versions différentes.

Dans chaque situation, le plug-in disposera de son propre moteur GraphQL privé et autonome sur lequel il pourra entièrement compter pour alimenter ses blocs Gutenberg (et nous n'avons pas à craindre de conflit).

Ce composant, qui s'appellera l' API privée GraphQL , devrait être prêt dans quelques semaines. (J'ai déjà commencé à travailler dessus.)

Par conséquent, ma recommandation est que, si vous souhaitez utiliser GraphQL pour alimenter les blocs Gutenberg dans votre plugin, veuillez attendre quelques semaines, puis consultez l'API GraphQL pour le jeune frère de WordPress, l'API privée GraphQL.

Conclusion

Même si j'ai de la peau dans le jeu, je pense avoir réussi à écrire un article essentiellement objectif.

J'ai été honnête en expliquant pourquoi et quand vous devez utiliser WPGraphQL. De même, j'ai été honnête en expliquant pourquoi l'API GraphQL pour WordPress semble être meilleure que WPGraphQL pour plusieurs cas d'utilisation.

De manière générale, nous pouvons résumer comme suit :

• Passez au statique avec WPGraphQL ou passez au direct avec l'API GraphQL pour WordPress.
• Jouez la sécurité avec WPGraphQL ou investissez (pour un gain potentiellement intéressant) dans l'API GraphQL pour WordPress.

Enfin, je souhaite que les frameworks Next.js soient repensés pour suivre la même approche que celle utilisée par Frontity : où ils peuvent accéder à une interface pour récupérer les données dont ils ont besoin, au lieu d'utiliser une implémentation directe d'une solution particulière ( l'actuel étant WPGraphQL). Si cela se produisait, les développeurs pourraient choisir le serveur sous-jacent à utiliser (qu'il s'agisse de WPGraphQL, de l'API GraphQL pour WordPress ou d'une autre solution introduite à l'avenir), en fonction de leurs besoins - d'un projet à l'autre.

Liens utiles

• WPGraphQL : documentation, page de téléchargement, référentiel de code
• API GraphQL pour WordPress : documentation, page de téléchargement, référentiel de code
• "L'atelier d'intégration de Gatsby WordPress"
  Vidéo YouTube avec démo de WPGraphQL
• "Introduction à l'API GraphQL pour WordPress"
  Vidéo YouTube avec démo de l'API GraphQL pour WordPress