🥳 ¡Lanzado Gato GraphQL v0.9!
Tras casi 1,5 años de desarrollo, y más de 16000 commits, ¡por fin se ha lanzado una nueva versión de Gato GraphQL! 🥳
La versión 0.9 es la mayor release en la historia del plugin. Aquí está el changelog, y aquí está el desglose completo de todas las nuevas características:
github.com/GatoGraphQL/GatoGraphQL/releases/tag/0.9.3
Este documento es bastante largo (¡más de 40 min de lectura!), así que abajo hay un TL;DR con los cambios más importantes.
Esquema GraphQL significativamente completado
El modelo de datos de WordPress se ha mapeado significativamente al esquema GraphQL.
Entre otros, el esquema tiene las siguientes mejoras:
- Consultar datos desde cualquier CPT, incluyendo desde cualquier theme y plugin
- Taxonomías personalizadas mapeadas (tags y categorías)
- Tipos GraphQL más adecuados creados y devueltos (ej:
HTML,URL,DateTime) - Field args organizados vía input objects
- Uso de oneof input objects para seleccionar una entidad por diferentes propiedades (ej:
id,slug) - Devolver payloads de mutation
- Consultar settings (de
wp_options) y valores meta (para posts, usuarios, comentarios y taxonomías)
Custom scalars
Se ha añadido soporte para tipos escalares personalizados al servidor GraphQL. Los custom scalars te permiten representar mejor tus datos, ya sea para obtener una entrada vía un argumento de campo, o imprimir una salida personalizada en la respuesta.
Se han implementado varios tipos escalares personalizados estándar, así que están listos para usarse en tu esquema GraphQL:
DateDateTimeEmailHTMLURLURLAbsolutePath
Custom enums
Los tipos enum personalizados ahora están soportados. Los enums son un tipo especial de escalar que está restringido a un conjunto particular de valores permitidos. Esto te permite:
- Validar que cualquier argumento de este tipo sea uno de los valores permitidos
- Comunicar a través del sistema de tipos que un campo siempre será uno de un conjunto finito de valores
Se han implementado varios tipos enum, y usado cuando es apropiado en el esquema GraphQL, incluyendo:
CommentOrderByEnumCommentStatusEnumCommentTypeEnumCustomPostOrderByEnumCustomPostStatusEnumMediaItemOrderByEnumMenuOrderByEnumTaxonomyOrderByEnumUserOrderByEnum
Input Objects
El servidor GraphQL ahora también soporta input types, y puedes añadir tus propios input objects al esquema GraphQL. Los input objects te permiten pasar objetos complejos como entradas a campos, lo que es particularmente útil para las mutations.
Se añadieron varios input objects donde fuera apropiado al esquema. Por ejemplo, los campos para consultar datos (como posts, users, comments, etc) reciben input objects complejos bajo los field args filter, sort y pagination, y los campos que mutan datos (como createPost, addCommentToCustomPost, etc) reciben un input object bajo el field arg input.
Oneof Input Objects
El "oneof" input object es un tipo particular de input object, donde exactamente uno de los input fields debe proporcionarse como entrada, o de lo contrario devuelve un error de validación. Este comportamiento introduce polimorfismo para entradas.
Por ejemplo, el campo Root.post ahora recibe un field argument by, que es un oneof input object que nos permite recuperar la entrada vía distintas propiedades, como por id o por slug:
{
postByID: post(by: {
id: 1
}) {
id
title
}
postBySlug: post(by: {
slug: "hello-world"
}) {
id
title
}
}El beneficio es que un único campo puede entonces usarse para abordar diferentes casos de uso, así podemos evitar crear un campo distinto para cada caso de uso (como postByID, postBySlug, etc), haciendo así el esquema GraphQL más lean y elegante.
Se han implementado varios Oneof Input Objects:
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
Las operaciones GraphQL (es decir, las operaciones query y mutation) ahora también pueden recibir directivas.
Restringir directivas a tipos específicos
Las directivas (de campo) pueden restringirse a aplicarse solo en campos de algún tipo específico. Por ejemplo, una directiva @strUpperCase que transforma el valor del campo a mayúsculas tiene sentido solo en campos String, no en Int o Float o Boolean. Esta restricción ahora puede declararse en el directive resolver.
Imprimir la ruta completa al nodo de la consulta GraphQL que produce errores
La respuesta ahora contiene la ruta completa a los nodos en la consulta GraphQL que devuelven un error (bajo la subentrada extensions.path), haciendo más fácil encontrar la fuente del problema.
Por ejemplo, en la siguiente consulta, la directiva @nonExisting no existe:
query {
myField @nonExisting
}La respuesta es la siguiente:
{
"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"
}
}Habilitar settings por defecto inseguros
Gato GraphQL proporciona settings por defecto seguros:
- El único endpoint está deshabilitado
- Los elementos de datos "sensibles" en el esquema GraphQL (como
User.roles, o filtrar entradas porstatus) no están expuestos - Solo unas pocas opciones de settings y meta keys (para entradas, usuarios, etc) pueden consultarse
- El número de entidades que pueden consultarse a la vez está limitado (para entradas, usuarios, etc)
Estos settings por defecto seguros son necesarios para hacer seguros los sitios "live", para prevenir ataques maliciosos. Sin embargo, no son necesarios al construir sitios "estáticos", donde el sitio WordPress no es vulnerable a ataques (como cuando es un sitio de desarrollo en un portátil, detrás de un firewall seguro, o no expuesto a Internet en general).
A partir de v0.9, podemos habilitar valores por defecto inseguros añadiendo en wp-config.php:
define( 'GRAPHQL_API_ENABLE_UNSAFE_DEFAULTS', true );Alternativamente, podemos definir esta misma key/value como una variable de entorno.
Al habilitar valores por defecto inseguros, los settings por defecto del plugin se transforman así:
- El único endpoint está habilitado
- Los elementos de datos "sensibles" están expuestos en el esquema GraphQL
- Todas las opciones de settings y meta keys pueden consultarse
- El número de entidades que pueden consultarse a la vez es ilimitado
Organizar Custom Endpoints y Persisted Queries por categoría
Al crear un Custom Endpoint o Persisted Query, podemos añadirle una "GraphQL endpoint category", para organizar todos nuestros endpoints:
Por ejemplo, podemos crear categorías para gestionar endpoints por cliente, aplicación, o cualquier otra pieza de información requerida:
En la lista de Custom Endpoints y Persisted Queries, podemos visualizar sus categorías y, haciendo clic en cualquier enlace de categoría, o usando el filtro en la parte superior, solo se mostrarán todas las entradas para esa categoría.
Consultar schema extensions vía introspección
Los metadatos personalizados adjuntos a los elementos del esquema ahora pueden consultarse vía el campo extensions.
Todos los elementos de introspección del esquema se han actualizado con el nuevo campo, cada uno de ellos devolviendo un objeto de un tipo "Extensions" correspondiente, que expone las propiedades personalizadas para ese elemento.
# 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!
}Terminado de desacoplar el código del servidor GraphQL de WordPress
El servidor GraphQL subyacente que potencia el plugin ahora puede instalarse y ejecutarse como componente PHP standalone, es decir, independientemente de WordPress.
Esto abre las puertas a usar Gato GraphQL con otros frameworks (ej: Laravel), y en cualquier entorno PHP, esté WordPress disponible o no (como al ejecutar una tarea de Integración Continua).
Navegar documentación al editar una Schema Configuration, Custom Endpoint y Persisted Query
Todos los bloques mostrados al editar una Schema Configuration, Custom Endpoint y Persisted Query ahora tienen un botón "info" que, al hacer clic, muestra documentación en una ventana modal.
Mucho más
Para descubrir todas las demás nuevas características, revisa la descripción completa de la nueva release, o navega el changelog.
Y descarga el plugin desde aquí.
Si te gusta lo que ves, por favor ayuda a difundir el amor ❤️