🥳 Gato GraphQL v0.9 wurde veröffentlicht!

Nach fast 1,5 Jahren Entwicklung und über 16.000 Commits wurde endlich eine neue Version von Gato GraphQL veröffentlicht! 🥳

Lade die neueste Version von Gato GraphQL herunter

Version 0.9 ist das größte Release in der Geschichte des Plugins. Hier ist das Changelog, und hier ist die vollständige Übersicht aller neuen Funktionen:

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

Dieses Dokument ist ziemlich lang (über 40 Min. Lesezeit!), daher findest du unten ein TL;DR mit den wichtigsten Änderungen.

GraphQL-Schema erheblich vervollständigt

Das WordPress-Datenmodell wurde erheblich in das GraphQL-Schema abgebildet.

GraphQL-Schema

Unter anderem weist das Schema folgende Verbesserungen auf:

Daten aus beliebigen CPTs abfragen, einschließlich aus Themes und Plugins
Benutzerdefinierte Taxonomien gemappt (Tags und Kategorien)
Passendere GraphQL-Typen erstellt und zurückgegeben (z. B.: HTML, URL, DateTime)
Feldargumente über Input Objects organisiert
Oneof Input Objects verwenden, um eine Entität über verschiedene Eigenschaften auszuwählen (z. B.: id, slug)
Mutation-Payloads zurückgeben
Einstellungen (aus wp_options) und Meta-Werte abfragen (für Posts, Benutzer, Kommentare und Taxonomien)

Custom scalars

Unterstützung für benutzerdefinierte Scalar-Typen wurde dem GraphQL-Server hinzugefügt. Custom Scalars ermöglichen es dir, deine Daten besser darzustellen – sei es zum Empfangen einer Eingabe über ein Feldargument oder zum Ausgeben einer angepassten Antwort.

Mehrere standardmäßige benutzerdefinierte Scalar-Typen wurden implementiert und stehen sofort für dein GraphQL-Schema zur Verfügung:

Date
DateTime
Email
HTML
URL
URLAbsolutePath

Custom enums

Benutzerdefinierte Enum-Typen werden jetzt unterstützt. Enums sind eine besondere Art von Scalar, die auf eine bestimmte Menge erlaubter Werte beschränkt ist. Das ermöglicht dir:

Zu validieren, dass beliebige Argumente dieses Typs einer der erlaubten Werte sind
Über das Typsystem zu kommunizieren, dass ein Feld immer einen Wert aus einer endlichen Menge hat

Mehrere Enum-Typen wurden implementiert und im GraphQL-Schema entsprechend eingesetzt, darunter:

CommentOrderByEnum
CommentStatusEnum
CommentTypeEnum
CustomPostOrderByEnum
CustomPostStatusEnum
MediaItemOrderByEnum
MenuOrderByEnum
TaxonomyOrderByEnum
UserOrderByEnum

Input Objects

Der GraphQL-Server unterstützt jetzt auch Input-Typen, und du kannst eigene Input Objects zum GraphQL-Schema hinzufügen. Input Objects ermöglichen es dir, komplexe Objekte als Eingaben an Felder zu übergeben, was besonders nützlich für Mutations ist.

Mehrere Input Objects wurden an passenden Stellen im Schema hinzugefügt. Zum Beispiel erhalten Felder zum Abfragen von Daten (wie posts, users, comments usw.) komplexe Input Objects unter den Feldargumenten filter, sort und pagination, und Felder, die Daten verändern (wie createPost, addCommentToCustomPost usw.), erhalten ein Input Object unter dem Feldargument input.

Oneof Input Objects

Das „oneof" Input Object ist eine besondere Art von Input Object, bei dem genau eines der Eingabefelder angegeben werden muss – andernfalls wird ein Validierungsfehler zurückgegeben. Dieses Verhalten führt Polymorphismus für Eingaben ein.

Zum Beispiel empfängt das Feld Root.post nun ein Feldargument by, das ein Oneof Input Object ist und es erlaubt, den Post über verschiedene Eigenschaften abzurufen, z. B. über id oder slug:

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

Der Vorteil ist, dass ein einziges Feld für verschiedene Anwendungsfälle genutzt werden kann, sodass wir vermeiden, für jeden Anwendungsfall ein separates Feld zu erstellen (wie postByID, postBySlug usw.), was das GraphQL-Schema schlanker und eleganter macht.

Mehrere Oneof Input Objects wurden implementiert:

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-Operationen (d. h. query- und mutation-Operationen) können jetzt auch Direktiven empfangen.

Direktiven auf bestimmte Typen einschränken

(Feld-)Direktiven können so eingeschränkt werden, dass sie nur auf Felder bestimmter Typen angewendet werden. Zum Beispiel macht eine Direktive @strUpperCase, die den Feldwert in Großbuchstaben umwandelt, nur bei String-Feldern Sinn, nicht bei Int, Float oder Boolean. Diese Einschränkung kann jetzt im Directive Resolver deklariert werden.

Den vollständigen Pfad zum fehlerverursachenden GraphQL-Query-Knoten ausgeben

Die Antwort enthält jetzt den vollständigen Pfad zu den Knoten in der GraphQL-Query, die einen Fehler zurückgeben (unter dem Untereintrag extensions.path), was es leichter macht, die Fehlerquelle zu finden.

Zum Beispiel existiert in der folgenden Query die Direktive @nonExisting nicht:

query {
  myField @nonExisting
}

Die Antwort lautet:

{
  "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"
  }
}

Unsichere Standardeinstellungen aktivieren

Gato GraphQL bietet sichere Standardeinstellungen:

Der Single Endpoint ist deaktiviert
Die „sensiblen" Datenelemente im GraphQL-Schema (wie User.roles oder das Filtern von Posts nach status) sind nicht exponiert
Nur eine Handvoll Einstellungsoptionen und Meta-Keys (für Posts, Benutzer usw.) können abgefragt werden
Die Anzahl der Entitäten, die gleichzeitig abgefragt werden können, ist begrenzt (für Posts, Benutzer usw.)

Diese sicheren Standardeinstellungen sind notwendig, um „live"-Seiten zu schützen und böswillige Angriffe zu verhindern. Sie werden jedoch nicht benötigt, wenn man „statische" Seiten baut, bei denen die WordPress-Site nicht anfällig für Angriffe ist (z. B. wenn es sich um eine Entwicklungssite auf einem Laptop handelt, die hinter einer sicheren Firewall liegt oder generell nicht mit dem Internet verbunden ist).

Ab v0.9 können unsichere Standardwerte aktiviert werden, indem du in wp-config.php folgendes hinzufügst:

define( 'GRAPHQL_API_ENABLE_UNSAFE_DEFAULTS', true );

Alternativ kann dieser Schlüssel/Wert als Umgebungsvariable definiert werden.

Wenn unsichere Standardwerte aktiviert werden, werden die Standard-Plugin-Einstellungen folgendermaßen verändert:

Der Single Endpoint ist aktiviert
Die „sensiblen" Datenelemente sind im GraphQL-Schema exponiert
Alle Einstellungsoptionen und Meta-Keys können abgefragt werden
Die Anzahl der Entitäten, die gleichzeitig abgefragt werden können, ist unbegrenzt

Custom Endpoints und Persisted Queries nach Kategorie organisieren

Beim Erstellen eines Custom Endpoints oder einer Persisted Query können wir eine „GraphQL endpoint category" hinzufügen, um alle unsere Endpoints zu organisieren:

Endpoint-Kategorien beim Bearbeiten eines Custom Endpoints

Zum Beispiel können wir Kategorien erstellen, um Endpoints nach Kunde, Anwendung oder anderen benötigten Informationen zu verwalten:

Liste der Endpoint-Kategorien

In der Liste der Custom Endpoints und Persisted Queries können wir deren Kategorien einsehen, und durch Klicken auf einen Kategorie-Link oder Verwenden des Filters oben werden nur die Einträge dieser Kategorie angezeigt.

Liste der Custom Endpoints mit ihren Kategorien

Schema Extensions via Introspektion abfragen

Benutzerdefinierte Metadaten, die an Schema-Elemente angehängt sind, können jetzt über das Feld extensions abgefragt werden.

Alle Introspektionselemente des Schemas wurden mit dem neuen Feld erweitert, jedes gibt ein Objekt eines entsprechenden „Extensions"-Typs zurück, der die benutzerdefinierten Eigenschaften für dieses Element bereitstellt.

# 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!
}

Entkopplung des GraphQL-Server-Codes von WordPress abgeschlossen

Der dem Plugin zugrunde liegende GraphQL-Server kann jetzt als eigenständige PHP-Komponente installiert und ausgeführt werden, d. h. unabhängig von WordPress.

Dies öffnet die Türen für die Nutzung von Gato GraphQL mit anderen Frameworks (z. B. Laravel) und in beliebigen PHP-Umgebungen, unabhängig davon, ob WordPress verfügbar ist oder nicht (z. B. beim Ausführen einer Continuous-Integration-Aufgabe).

Dokumentation beim Bearbeiten einer Schema Configuration, eines Custom Endpoints und einer Persisted Query durchsuchen

Alle Blöcke, die beim Bearbeiten einer Schema Configuration, eines Custom Endpoints und einer Persisted Query angezeigt werden, haben jetzt einen „Info"-Button, der beim Klicken die Dokumentation in einem modalen Fenster anzeigt.

Klick auf einen 'Info'-Button...

...öffnet ein modales Fenster mit der Dokumentation

Noch viel mehr

Um alle anderen neuen Funktionen zu entdecken, lies die vollständige Beschreibung des neuen Releases oder sieh dir das Changelog an.

Und lade das Plugin hier herunter.

Wenn dir gefällt, was du siehst, hilf uns, die Liebe zu verbreiten ❤️

🥳 Gato GraphQL v0.9 wurde veröffentlicht!

Abonniere unseren Newsletter