🥳 Gato GraphQL v0.9 est sorti !

Après près de 1,5 an de développement, et plus de 16 000 commits, une nouvelle version de Gato GraphQL a enfin été publiée ! 🥳

La version 0.9 est la plus grande release de l'histoire du plugin. Voici le changelog, et voici le détail complet de toutes les nouvelles fonctionnalités :

github.com/GatoGraphQL/GatoGraphQL/releases/tag/0.9.3

Ce document est assez long (plus de 40 min de lecture !), donc voici un TL;DR avec les changements les plus importants.

​

Schéma GraphQL considérablement complété

Le modèle de données WordPress a été considérablement mappé dans le schéma GraphQL.

Parmi d'autres, le schéma présente les améliorations suivantes :

• Requêter des données depuis n'importe quel CPT, y compris depuis n'importe quel thème et plugin
• Taxonomies personnalisées mappées (tags et catégories)
• Types GraphQL plus appropriés créés et retournés (ex : HTML, URL, DateTime)
• Arguments de champ organisés via des input objects
• Utilisation des oneof input objects pour sélectionner une entité par différentes propriétés (ex : id, slug)
• Retourner des payloads de mutation
• Requêter les paramètres (depuis wp_options) et les valeurs meta (pour les posts, utilisateurs, commentaires et taxonomies)

​

Custom scalars

Le support des types scalaires personnalisés a été ajouté au serveur GraphQL. Les custom scalars vous permettent de mieux représenter vos données, que ce soit pour obtenir une entrée via un argument de champ, ou pour imprimer une sortie personnalisée dans la réponse.

Plusieurs types scalaires personnalisés standard ont été implémentés, ils sont donc immédiatement disponibles pour être utilisés dans votre schéma GraphQL :

• Date
• DateTime
• Email
• HTML
• URL
• URLAbsolutePath

​

Custom enums

Les types enum personnalisés sont désormais pris en charge. Les enums sont un type spécial de scalaire restreint à un ensemble particulier de valeurs autorisées. Cela vous permet de :

• Valider que tout argument de ce type est l'une des valeurs autorisées
• Communiquer via le système de types qu'un champ sera toujours l'une d'un ensemble fini de valeurs

Plusieurs types enum ont été implémentés, et utilisés lorsque c'est approprié dans le schéma GraphQL, notamment :

• CommentOrderByEnum
• CommentStatusEnum
• CommentTypeEnum
• CustomPostOrderByEnum
• CustomPostStatusEnum
• MediaItemOrderByEnum
• MenuOrderByEnum
• TaxonomyOrderByEnum
• UserOrderByEnum

​

Input Objects

Le serveur GraphQL prend désormais également en charge les input types, et vous pouvez ajouter vos propres input objects au schéma GraphQL. Les input objects vous permettent de passer des objets complexes en entrée de champs, ce qui est particulièrement utile pour les mutations.

Plusieurs input objects ont été ajoutés là où c'était approprié dans le schéma. Par exemple, les champs pour requêter des données (comme posts, users, comments, etc.) reçoivent des input objects complexes sous les arguments de champ filter, sort et pagination, et les champs qui mutent des données (comme createPost, addCommentToCustomPost, etc.) reçoivent un input object sous l'argument de champ input.

​

Oneof Input Objects

Le "oneof" input object est un type particulier d'input object, où exactement un des champs d'entrée doit être fourni comme entrée, sinon il retourne une erreur de validation. Ce comportement introduit le polymorphisme pour les entrées.

Par exemple, le champ Root.post reçoit maintenant un argument de champ by, qui est un oneof input object permettant de récupérer le post via différentes propriétés, comme par id ou par slug :

{
  postByID: post(by: {
    id: 1
  }) {
    id
    title
  }
 
  postBySlug: post(by: {
    slug: "hello-world"
  }) {
    id
    title
  }
}Copy

L'avantage est qu'un seul champ peut alors être utilisé pour traiter différents cas d'usage, ce qui nous évite de créer un champ différent pour chaque cas d'usage (comme postByID, postBySlug, etc.), rendant ainsi le schéma GraphQL plus léger et élégant.

Plusieurs Oneof Input Objects ont été implémentés :

• Root.customPost(by:)
• Root.mediaItem(by:)
• Root.menu(by:)
• Root.page(by:)
• Root.postCategory(by:)
• Root.postTag(by:)
• Root.post(by:)
• Root.user(by:)

​

Operation Directives

Les opérations GraphQL (c'est-à-dire les opérations query et mutation) peuvent désormais également recevoir des directives.

​

Restreindre les directives à des types spécifiques

Les directives (de champ) peuvent être restreintes pour ne s'appliquer qu'aux champs d'un type spécifique. Par exemple, une directive @strUpperCase qui transforme la valeur du champ en majuscules n'a de sens que sur les champs String, pas sur Int ou Float ou Boolean. Cette restriction peut maintenant être déclarée dans le directive resolver.

​

Afficher le chemin complet vers le nœud de la requête GraphQL qui produit des erreurs

La réponse contient maintenant le chemin complet vers les nœuds dans la requête GraphQL qui retournent une erreur (sous l'entrée extensions.path), ce qui facilite la recherche de la source du problème.

Par exemple, dans la requête suivante, la directive @nonExisting n'existe pas :

query {
  myField @nonExisting
}Copy

La réponse est la suivante :

{
  "errors": [
    {
      "message": "There is no directive with name 'nonExisting'",
      "locations": [
        {
          "line": 2,
          "column": 7
        }
      ],
      "extensions": {
        "type": "QueryRoot",
        "field": "myField @nonExisting",
        "path": [
          "@nonExisting",
          "myField @nonExisting",
          "query { ... }"
        ],
        "code": "PoP\\ComponentModel\\e20"
      }
    }
  ],
  "data": {
    "id": "root"
  }
}Copy

​

Activer les paramètres par défaut non sécurisés

Gato GraphQL fournit des paramètres par défaut sécurisés :

• L'endpoint unique est désactivé
• Les éléments de données « sensibles » dans le schéma GraphQL (comme User.roles, ou le filtrage des posts par status) ne sont pas exposés
• Seule une poignée d'options de paramètres et de meta keys (pour les posts, utilisateurs, etc.) peut être requêtée
• Le nombre d'entités qui peuvent être requêtées à la fois est limité (pour les posts, utilisateurs, etc.)

Ces paramètres par défaut sécurisés sont nécessaires pour sécuriser les sites « live », afin de prévenir les attaques malveillantes. Cependant, ils ne sont pas nécessaires lors de la construction de sites « statiques », où le site WordPress n'est pas vulnérable aux attaques (comme lorsqu'il s'agit d'un site de développement sur un ordinateur portable, derrière un pare-feu sécurisé, ou non exposé à Internet en général).

À partir de v0.9, nous pouvons activer les valeurs par défaut non sécurisées en ajoutant dans wp-config.php :

define( 'GRAPHQL_API_ENABLE_UNSAFE_DEFAULTS', true );Copy

Alternativement, nous pouvons définir cette même clé/valeur comme variable d'environnement.

Lors de l'activation des valeurs par défaut non sécurisées, les paramètres par défaut du plugin sont transformés ainsi :

• L'endpoint unique est activé
• Les éléments de données « sensibles » sont exposés dans le schéma GraphQL
• Toutes les options de paramètres et meta keys peuvent être requêtées
• Le nombre d'entités qui peuvent être requêtées à la fois est illimité

​

Organiser les Custom Endpoints et Persisted Queries par catégorie

Lors de la création d'un Custom Endpoint ou d'une Persisted Query, nous pouvons lui ajouter une « GraphQL endpoint category », pour organiser tous nos endpoints :

Par exemple, nous pouvons créer des catégories pour gérer les endpoints par client, application, ou toute autre information requise :

Dans la liste des Custom Endpoints et Persisted Queries, nous pouvons visualiser leurs catégories et, en cliquant sur n'importe quel lien de catégorie, ou en utilisant le filtre en haut, seules toutes les entrées de cette catégorie seront affichées.

​

Requêter les schema extensions via l'introspection

Les métadonnées personnalisées attachées aux éléments du schéma peuvent maintenant être requêtées via le champ extensions.

Tous les éléments d'introspection du schéma ont été mis à niveau avec le nouveau champ, chacun d'eux retournant un objet d'un type « Extensions » correspondant, qui expose les propriétés personnalisées pour cet élément.

# Using "_" instead of "__" in introspection type name to avoid errors in graphql-js
type _SchemaExtensions {
  # Is the schema being namespaced?
  isNamespaced: Boolean!
}
 
extend type __Schema {
  extensions: _SchemaExtensions!
}
 
type _NamedTypeExtensions {
  # The type name
  elementName: String!
 
  # The "namespaced" type name
  namespacedName: String!
 
  # Enum-like "possible values" for EnumString type resolvers, `null` otherwise
  possibleValues: [String!]
 
  # OneOf Input Objects are a special variant of Input Objects where the type system asserts that exactly one of the fields must be set and non-null, all others being omitted.
  isOneOf: Boolean!
}
 
extend type __Type {
  # Non-null for named types, null for wrapping types (Non-Null and List)
  extensions: _NamedTypeExtensions
}
 
type _DirectiveExtensions {
  # If no objects are returned in the field (eg: because they failed validation), does the directive still need to be executed?
  needsDataToExecute: Boolean!
 
  # Names or descriptions of the types the field directives is restricted to, or `null` if it supports any type (i.e. it defines no restrictions)
  fieldDirectiveSupportedTypeNamesOrDescriptions: [String!]
}
 
extend type __Directive {
  extensions: _DirectiveExtensions!
}
 
type _FieldExtensions {
  isGlobal: Boolean!
 
  # Useful for nested mutations
  isMutation: Boolean!
 
  # `true` => Only exposed when "Expose "sensitive" data elements" is enabled
  isSensitiveDataElement: Boolean!
}
 
extend type __Field {
  extensions: _FieldExtensions!
}
 
type _InputValueExtensions {
  isSensitiveDataElement: Boolean!
}
 
extend type __InputValue {
  extensions: _InputValueExtensions!
}
 
type _EnumValueExtensions {
  isSensitiveDataElement: Boolean!
}
 
extend type __EnumValue {
  extensions: _EnumValueExtensions!
}Copy

​

Finalisation du découplage du code du serveur GraphQL de WordPress

Le serveur GraphQL sous-jacent qui alimente le plugin peut maintenant être installé et exécuté comme composant PHP autonome, c'est-à-dire indépendamment de WordPress.

Cela ouvre la porte à l'utilisation de Gato GraphQL avec d'autres frameworks (ex : Laravel), et dans n'importe quel environnement PHP, que WordPress soit disponible ou non (comme lors de l'exécution d'une tâche d'Intégration Continue).

​

Parcourir la documentation lors de l'édition d'une Schema Configuration, Custom Endpoint et Persisted Query

Tous les blocs affichés lors de l'édition d'une Schema Configuration, Custom Endpoint et Persisted Query disposent maintenant d'un bouton « info » qui, lorsqu'on clique dessus, affiche la documentation dans une fenêtre modale.

​

Bien plus encore

Pour découvrir toutes les autres nouvelles fonctionnalités, consultez la description complète de la nouvelle release, ou parcourez le changelog.

Et téléchargez le plugin depuis ici.

Si vous aimez ce que vous voyez, aidez à faire passer le message ❤️