🥳 Gato GraphQL v0.9 is uitgebracht!
Na bijna 1,5 jaar ontwikkeling en meer dan 16.000 commits is er eindelijk een nieuwe versie van Gato GraphQL uitgebracht! 🥳
Versie 0.9 is de grootste release in de geschiedenis van de plugin. Hier is de changelog, en hier vind je een volledig overzicht van alle nieuwe functies:
github.com/GatoGraphQL/GatoGraphQL/releases/tag/0.9.3
Dit document is behoorlijk lang (meer dan 40 minuten leestijd!), dus hieronder vind je een TL;DR met de belangrijkste wijzigingen.
Aanzienlijk uitgebreid GraphQL-schema
Het WordPress-datamodel is in grote mate in kaart gebracht in het GraphQL-schema.
Het schema bevat onder andere de volgende verbeteringen:
- Query-data uit elk CPT, inclusief van elk thema en elke plugin
- Aangepaste taxonomieën in kaart gebracht (tags en categorieën)
- Meer passende GraphQL-typen aangemaakt en teruggegeven (bijv.:
HTML,URL,DateTime) - Veldargumenten georganiseerd via input objects
- Gebruik van oneof input objects om een entiteit te selecteren op basis van verschillende eigenschappen (bijv.:
id,slug) - Mutatie-payloads teruggeven
- Instellingen (uit
wp_options) en metawaarden (voor posts, gebruikers, reacties en taxonomieën) opvragen
Custom scalars
Ondersteuning voor aangepaste scalaire typen is toegevoegd aan de GraphQL-server. Custom scalars stellen je in staat je gegevens beter te representeren, zowel voor het ontvangen van invoer via een veldargument als voor het afdrukken van aangepaste uitvoer in de response.
Er zijn verschillende standaard aangepaste scalaire typen geïmplementeerd, die direct beschikbaar zijn voor gebruik in je GraphQL-schema:
DateDateTimeEmailHTMLURLURLAbsolutePath
Custom enums
Aangepaste enum-typen worden nu ondersteund. Enums zijn een speciaal soort scalar die beperkt is tot een bepaalde set toegestane waarden. Dit stelt je in staat om:
- Te valideren dat elk argument van dit type een van de toegestane waarden is
- Via het typesysteem te communiceren dat een veld altijd een van een eindige reeks waarden zal zijn
Er zijn verschillende enum-typen geïmplementeerd en overal waar passend gebruikt in het GraphQL-schema, waaronder:
CommentOrderByEnumCommentStatusEnumCommentTypeEnumCustomPostOrderByEnumCustomPostStatusEnumMediaItemOrderByEnumMenuOrderByEnumTaxonomyOrderByEnumUserOrderByEnum
Input Objects
De GraphQL-server ondersteunt nu ook input-typen, en je kunt je eigen input objects aan het GraphQL-schema toevoegen. Input objects stellen je in staat om complexe objecten als invoer aan velden door te geven, wat vooral handig is bij mutaties.
Er zijn meerdere input objects toegevoegd waar dat van toepassing was in het schema. Zo ontvangen velden voor het opvragen van gegevens (zoals posts, users, comments, enz.) complexe input objects onder de veldargumenten filter, sort en pagination, en velden die gegevens muteren (zoals createPost, addCommentToCustomPost, enz.) ontvangen een input object onder het veldargument input.
Oneof Input Objects
Het "oneof" input object is een bijzonder type input object waarbij precies één van de invoervelden als invoer moet worden opgegeven, anders geeft het een validatiefout terug. Dit gedrag introduceert polymorfisme voor invoer.
Het veld Root.post ontvangt nu bijvoorbeeld een veldargument by, dat een oneof input object is waarmee de post via verschillende eigenschappen kan worden opgehaald, zoals via id of via slug:
{
postByID: post(by: {
id: 1
}) {
id
title
}
postBySlug: post(by: {
slug: "hello-world"
}) {
id
title
}
}Het voordeel is dat één veld dan voor verschillende gebruiksscenario's kan worden ingezet, zodat we het aanmaken van een apart veld voor elk scenario (zoals postByID, postBySlug, enz.) kunnen vermijden, waardoor het GraphQL-schema compacter en eleganter wordt.
Er zijn meerdere Oneof Input Objects geïmplementeerd:
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
GraphQL-operaties (d.w.z. query- en mutation-operaties) kunnen nu ook directives ontvangen.
Directives beperken tot specifieke typen
(Veld-)directives kunnen worden beperkt zodat ze alleen worden toegepast op velden van bepaalde specifieke typen. Een directive @strUpperCase die de veldwaarde naar hoofdletters transformeert heeft bijvoorbeeld alleen zin voor String-velden, niet voor Int, Float of Boolean. Deze beperking kan nu worden gedeclareerd in de directive-resolver.
Volledig pad naar het GraphQL query-knooppunt dat fouten produceert weergeven
De response bevat nu het volledige pad naar de knooppunten in de GraphQL query die een fout retourneren (onder de subvermelding extensions.path), waardoor het gemakkelijker is de bron van het probleem te vinden.
In de volgende query bestaat de directive @nonExisting bijvoorbeeld niet:
query {
myField @nonExisting
}De response is als volgt:
{
"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"
}
}Onveilige standaardinstellingen inschakelen
Gato GraphQL biedt veilige standaardinstellingen:
- Het enkelvoudige endpoint is uitgeschakeld
- De "gevoelige" gegevenselementen in het GraphQL-schema (zoals
User.rolesof het filteren van posts opstatus) zijn niet blootgesteld - Slechts een handvol instellingsopties en metasleutels (voor posts, gebruikers, enz.) kunnen worden opgevraagd
- Het aantal entiteiten dat tegelijk kan worden opgevraagd is beperkt (voor posts, gebruikers, enz.)
Deze veilige standaardinstellingen zijn nodig om "live" sites te beveiligen en kwaadaardige aanvallen te voorkomen. Ze zijn echter niet nodig bij het bouwen van "statische" sites, waarbij de WordPress-site niet kwetsbaar is voor aanvallen (zoals wanneer het een ontwikkelingssite op een laptop is, achter een veilige firewall staat, of in het algemeen niet aan het internet is blootgesteld).
Vanaf v0.9 kun je onveilige standaardinstellingen inschakelen door het volgende toe te voegen aan wp-config.php:
define( 'GRAPHQL_API_ENABLE_UNSAFE_DEFAULTS', true );Als alternatief kun je dezelfde sleutel/waarde definiëren als een omgevingsvariabele.
Wanneer onveilige standaardinstellingen worden ingeschakeld, worden de standaard plugin-instellingen als volgt getransformeerd:
- Het enkelvoudige endpoint is ingeschakeld
- De "gevoelige" gegevenselementen zijn blootgesteld in het GraphQL-schema
- Alle instellingsopties en metasleutels kunnen worden opgevraagd
- Het aantal entiteiten dat tegelijk kan worden opgevraagd is onbeperkt
Custom Endpoints en Persisted Queries organiseren per categorie
Bij het aanmaken van een Custom Endpoint of Persisted Query kun je er een "GraphQL endpoint-categorie" aan toevoegen om alle endpoints te organiseren:
Je kunt bijvoorbeeld categorieën aanmaken om endpoints per klant, applicatie of andere gewenste informatie te beheren:
In de lijst met Custom Endpoints en Persisted Queries kun je hun categorieën bekijken, en door op een categorielink te klikken of het filter bovenaan te gebruiken, worden alleen de vermeldingen van die categorie weergegeven.
Schema-extensies opvragen via introspectie
Aangepaste metadata die aan schema-elementen is gekoppeld, kan nu worden opgevraagd via het veld extensions.
Alle introspectie-elementen van het schema zijn uitgebreid met het nieuwe veld, waarbij elk van hen een object van een overeenkomstig "Extensions"-type teruggeeft, dat de aangepaste eigenschappen van dat element blootstelt.
# 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!
}Ontkoppeling van de GraphQL-servercode van WordPress voltooid
De onderliggende GraphQL-server die de plugin aandrijft, kan nu als een zelfstandig PHP-component worden geïnstalleerd en uitgevoerd, d.w.z. onafhankelijk van WordPress.
Dit opent de deur naar het gebruik van Gato GraphQL met andere frameworks (bijv.: Laravel) en in elke PHP-omgeving, ongeacht of WordPress beschikbaar is of niet (zoals bij het uitvoeren van een Continuous Integration-taak).
Documentatie bekijken bij het bewerken van een Schema Configuration, Custom Endpoint en Persisted Query
Alle blokken die worden weergegeven bij het bewerken van een Schema Configuration, Custom Endpoint en Persisted Query hebben nu een "info"-knop die, wanneer erop wordt geklikt, documentatie in een modaal venster toont.
Nog veel meer
Bekijk de volledige beschrijving van de nieuwe release om alle andere nieuwe functies te ontdekken, of blader door de changelog.
Als je blij bent met wat je ziet, help dan de liefde te verspreiden ❤️