Schema Functions
Schema FunctionsPHP Functions via Schema

PHP Functions via Schema

Included in the “Power Extensions” bundle

此扩展为 GraphQL schema 添加了字段和指令,用于公开编程语言(如 PHP)中常见的功能。

描述

函数字段和指令在数据检索后非常有用,可以按需转换字段值,并提供强大的数据导入/导出能力。

以下包含多种函数字段和指令的 Query:

{
  _intAdd(add: 15, to: 56)
  _intArraySum(array: [1, 2, 3, 4, 5])
 
  _arrayJoin(array: ["Hello", "to", "everyone"], separator: " ")
  _arrayItem(array: ["one", "two", "three", "four", "five"], position: 3)
  _arraySearch(array: ["uno", "dos", "tres", "cuatro", "cinco"], element: "tres")
  _arrayUnique(array: ["uno", "dos", "uno", "tres", "cuatro", "dos", "cinco", "dos"])
  _arrayMerge(arrays: [["uno", "dos", "uno"], ["tres", "cuatro", "dos", "cinco", "dos"]])
  _arrayDiff(arrays: [["uno", "dos"], ["tres", "cuatro", "dos"]])
  _arrayAddItem(array: ["uno", "dos"], value: "tres")
  _arraySetItem(array: ["uno", "dos"], index: 0, value: "tres")
  _arrayKeys(array: ["uno", "dos", "tres"])
  _arrayLength(array: ["uno", "dos", "tres"])
 
  _strRegexFindMatches(regex: "/https?:\\/\\/([a-zA-Z0-9][a-zA-Z0-9-]{1,61}[a-zA-Z0-9]\\.[a-zA-Z]{2,})/", string: "In website https://gatographql.com there is more information")
  
  _strReplace(search: "https://", replaceWith: "http://", in: "https://gatographql.com")
  _strReplaceMultiple(search: ["https://", "gato"], replaceWith: ["http://", "dog"], in: "https://gatographql.com")
  _strRegexReplace(searchRegex: "/^https?:\\/\\//", replaceWith: "", in: "https://gatographql.com")
  _strRegexReplaceMultiple(searchRegex: ["/^https?:\\/\\//", "/([a-z]*)/"], replaceWith: ["", "$1$1"], in: "https://gatographql.com")
  
  _strStartsWith(search: "orld", in: "Hello world")
  _strEndsWith(search: "orld", in: "Hello world")
  _strUpperCase(text: "Hello world")
  _strLowerCase(text: "Hello world")
  _strTitleCase(text: "Hello world")
 
 
  falseToTrue: _echo(value: false) @boolOpposite
  trueToFalse: _echo(value: true) @boolOpposite
  plusOne: _echo(value: 2) @intAdd(number: 1)
  objectAddEntry: _echo(value: {
    user: "Leo",
    contact: {
      email: "leo@test.com"
    }
  })
    @objectAddEntry(key: "phone", value: "+0929094229", underPath: "contact")
    @objectAddEntry(key: "methods", value: {}, underPath: "contact")
    @objectAddEntry(key: "card", value: true, underPath: "contact.methods")
  upperCase: _echo(value: "Hello world") @strUpperCase
  lowerCase: _echo(value: "Hello world") @strLowerCase
  titleCase: _echo(value: "Hello world") @strTitleCase
  append: _echo(value: "Hello world") @strAppend(string: "!!!")
  prepend: _echo(value: "Hello world") @strPrepend(string: "!!!")
  arraySplice: _echo(value: ["uno", "dos", "tres"]) @arraySplice(offset: 1)
  arraySpliceWithLength: _echo(value: ["uno", "dos", "tres"]) @arraySplice(offset: 1, length: 1)
  arraySpliceWithReplacement: _echo(value: ["uno", "dos", "tres"]) @arraySplice(offset: 1, replacement: ["cuatro", "cinco"])
  arraySpliceWithLengthAndReplacement: _echo(value: ["uno", "dos", "tres"]) @arraySplice(offset: 1, length: 1, replacement: ["cuatro", "cinco"])
  arrayUnique: _echo(value: ["uno", "dos", "uno", "tres", "cuatro", "dos", "cinco", "dos"]) @arrayUnique
  arrayMerge: _echo(value: ["uno", "dos", "uno"]) @arrayMerge(with: ["tres", "cuatro", "dos", "cinco", "dos"])
  arrayDiff: _echo(value: ["uno", "dos"]) @arrayDiff (against: ["tres", "cuatro", "dos"])
  arrayFilter: _echo(value: ["uno", "dos", null, "tres", "", "dos", []]) @arrayFilter
  objectKeepProperties: _echo(value: { user: "Leo", email: "leo@test.com" } )
    @objectKeepProperties(
      keys: ["user"]
    )
}

...将生成:

{
  "data": {
    "_intAdd": 71,
    "_intArraySum": 15,
    "_arrayJoin": "Hello to everyone",
    "_arrayItem": "four",
    "_arraySearch": 2,
    "_arrayUnique": [
      "uno",
      "dos",
      "tres",
      "cuatro",
      "cinco"
    ],
    "_arrayMerge": [
      "uno",
      "dos",
      "uno",
      "tres",
      "cuatro",
      "dos",
      "cinco",
      "dos"
    ],
    "_arrayDiff": [
      "uno"
    ],
    "_arrayAddItem": [
      "uno",
      "dos",
      "tres"
    ],
    "_arraySetItem": [
      "tres",
      "dos"
    ],
    "_arrayKeys": [
      0,
      1,
      2
    ],
    "_arrayLength": 3,
    "_strRegexFindMatches": [
      [
        "https:\/\/gatographql.com"
      ],
      [
        "gatographql.com"
      ]
    ],
    "_strReplace": "http://gatographql.com",
    "_strReplaceMultiple": "http://doggraphql.com",
    "_strRegexReplace": "gatographql.com",
    "_strRegexReplaceMultiple": "gatographqlgatographql.comcom",
    "_strStartsWith": false,
    "_strEndsWith": true,
    "_strUpperCase": "HELLO WORLD",
    "_strLowerCase": "hello world",
    "_strTitleCase": "Hello World",
    "falseToTrue": true,
    "trueToFalse": false,
    "plusOne": 3,
    "objectAddEntry": {
      "user": "Leo",
      "contact": {
        "email": "leo@test.com",
        "phone": "+0929094229",
        "methods": {
          "card": true
        }
      }
    },
    "upperCase": "HELLO WORLD",
    "lowerCase": "hello world",
    "titleCase": "Hello World",
    "append": "Hello world!!!",
    "prepend": "!!!Hello world",
    "arraySplice": [
      "uno"
    ],
    "arraySpliceWithLength": [
      "uno",
      "tres"
    ],
    "arraySpliceWithReplacement": [
      "uno",
      "cuatro",
      "cinco"
    ],
    "arraySpliceWithLengthAndReplacement": [
      "uno",
      "cuatro",
      "cinco",
      "tres"
    ],
    "arrayUnique": [
      "uno",
      "dos",
      "tres",
      "cuatro",
      "cinco"
    ],
    "arrayMerge": [
      "uno",
      "dos",
      "uno",
      "tres",
      "cuatro",
      "dos",
      "cinco",
      "dos"
    ],
    "arrayDiff": [
      "uno"
    ],
    "arrayFilter": [
      "uno",
      "dos",
      "tres",
      "dos"
    ],
    "objectKeepProperties": {
      "user": "Leo"
    }
  }
}

函数字段

函数字段是全局字段,因此会被添加到 GraphQL schema 中的每一个类型:不仅在 QueryRoot 中,也在 PostUser 等类型中。

以下是函数字段列表。

_and

对多个布尔型属性执行 AND 运算并返回结果。

_arrayAddItem

向数组中添加一个元素。

_arrayCombine

使用一个数组的元素作为键,另一个数组的元素作为值,创建一个 JSON 对象。

_arrayChunk

将数组分割为若干块。

_arrayDiff

返回一个数组,其中包含第一个数组中存在但在其他任何数组中均不存在的所有元素。

_arrayEncodeAsJSONString

将数组编码为 JSON 字符串。

_arrayFill

创建一个用指定值填充的数组。

_arrayFilter

过滤掉数组中的 null 或空元素。

_arrayFlipToObject

将数组中所有数字键与其关联值互换,并返回一个对象。

_arrayInnerJoinJSONObjectProperties

用源数组中 JSON 对象的属性填充目标数组中的 JSON 对象,条件是两个对象的某个属性值相同。

_arrayItem

访问数组中指定位置的元素。

_arrayJoin

使用指定的分隔符将数组中的所有字符串连接起来。

_arrayKeys

返回数组中的键。

_arrayLength

返回数组中的元素数量。

_arrayMerge

将两个或多个数组合并在一起。

_arrayPad

用指定值将数组填充至指定长度。

_arrayRandom

从提供的元素中随机选择一个。

_arrayRemoveFirst

删除数组中的第一个元素。

_arrayRemoveLast

删除数组中的最后一个元素。

_arrayReverse

反转数组。

_arraySearch

搜索某个元素在数组中的位置。如果找到,返回其位置;否则返回 false

_arraySetItem

在数组的指定位置设置一个元素。

_arraySlice

从数组中提取一个片段。

_arraySplice

删除数组的一部分并用其他内容替换。

_arrayUnique

过滤掉数组中所有重复的元素。

_date

根据给定的格式字符串,使用给定的整数 timestamp(Unix 时间戳)或在未提供时间戳时使用当前时间,返回格式化后的字符串。换言之,timestamp 是可选的,默认值为 time() 的返回值(通过字段 _time 提供)。

_echo

原样返回输入值。

_equals

指示某个字段的结果是否等于某个特定值。

_floatCeil

将数字向上取整到下一个最大整数。

_floatDivide

将一个数除以另一个数。

_greaterThan

指示 number1 > number2。

_greaterThanOrEquals

指示 number1 >= number2。

_if

如果一个布尔型属性为 true,则执行某个字段;否则执行另一个字段。

_inArray

指示数组是否包含该值。

_intAdd

将一个整数加到另一个整数上。

_intArraySum

返回数组中整数元素的总和。

_intMultiply

将一个整数与另一个整数相乘。

_intSubtract

从一个整数中减去另一个整数。

_isEmpty

指示某个值是否为空。

_isNull

指示某个值是否为 null。

_lowerThan

指示 number1 < number2。

_lowerThanOrEquals

指示 number1 <= number2。

_makeTime

返回与给定参数对应的 Unix 时间戳。该时间戳是一个长整数,包含从 Unix 纪元(1970年1月1日 00:00:00 GMT)到指定时间的秒数。

任何被省略或设为 null 的可选参数,将根据本地日期和时间设置为当前值。

_not

返回布尔型属性的相反值。

_notEmpty

指示值是否不为空。

_notEquals

指示两个值是否互不相等。

_notInArray

指示数组是否不包含该值。

_notNull

指示值是否不为 null

_objectAddEntry

向对象中添加一个条目。

_objectEncodeAsJSONString

将对象编码为 JSON 字符串。

_objectFilter

过滤掉对象中的 null 或空元素。

_objectFlip

翻转 JSON 对象中的键和值。

_objectIntersectKey

使用键进行比较,计算对象的交集。

_objectKeepProperties

仅保留 JSON 对象中的特定属性。

_objectMerge

将两个或多个对象合并在一起。

_objectProperties

获取 JSON 对象中的属性。

_objectProperty

从 JSON 对象中获取某个属性。

_objectRemoveEntry

从 JSON 对象中删除一个条目。

_objectRemoveProperties

从 JSON 对象中删除一个或多个条目。

_objectValues

获取 JSON 对象中的值。

_or

对多个布尔型属性执行 OR 运算并返回结果。

_propertyExistsInJSONObject

指示某个属性是否存在于 JSON 对象中。

_propertyIsSetInJSONObject

指示某个属性是否存在于 JSON 对象中且不为 null

_sprintf

将字符串中的占位符替换为提供的值。

_strAppend

在一个字符串的末尾追加另一个字符串。

_strArrayReplace

将数组中的某个字符串替换为另一个字符串。

_strArrayReplaceMultiple

将数组中的一组字符串替换为另一组字符串。

_strContains

指示一个字符串是否包含另一个字符串。

_strDecodeJSONObject

将字符串解码为 JSON 对象,如果无法解码则返回 null

_strDecodeList

将字符串解码为数组(任意类型),如果无法解码则返回 null

_strEndsWith

指示一个字符串是否以另一个字符串结尾。

_strLength

返回字符串的长度。

_strLowerCase

将字符串转换为小写。

_strPad

使用另一个字符串将字符串填充至指定长度。

_strPos

返回子字符串在字符串中的位置,如果未找到则返回 null

_strRegexFindMatches

执行正则表达式以提取字符串中的所有匹配项。

_strRegexReplace

执行正则表达式以搜索并替换字符串。

_strRegexReplaceMultiple

执行正则表达式以搜索并替换多个字符串。

_strRepeat

重复一个字符串。

_strReplace

将一个字符串替换为另一个字符串。

_strReplaceMultiple

将一组字符串替换为另一组字符串。

_strReverse

反转字符串。

_strShuffle

随机打乱字符串。

_strStartsWith

指示一个字符串是否以另一个字符串开头。

_strStripSlashes

返回去除了反斜杠的字符串。(\' 变为 ',以此类推。) 双反斜杠 (\\) 变为单反斜杠 (\)。

_strSubstr

返回字符串的一部分。

_strTitleCase

将字符串转换为标题大小写。

_strToTime

将任意英文文本形式的日期时间描述解析为 Unix 时间戳。

_strTrim

去除字符串开头和结尾的空白(或其他字符)。

_strUpperCase

将字符串转换为大写。

_strWordCount

返回字符串中的单词数量。

_time

返回当前时间。

函数指令

以下是函数指令列表。

@arrayAddItem

向数组中添加一个元素。

@arrayDiff

计算与另一个数组的差集。

@arrayFilter

过滤掉数组中的 null 或空元素。

@arrayMerge

将数组与另一个数组合并。

@arrayPad

用指定值将数组填充至指定长度。

@arrayRemoveFirst

删除数组中的第一个元素。

@arrayRemoveLast

删除数组中的最后一个元素。

@arrayReverse

反转数组。

@arraySetItem

在数组的指定位置设置一个元素。

@arraySlice

从数组中提取一个片段。

@arraySplice

删除数组的一部分并用其他内容替换。

@arrayUnique

过滤掉数组中所有重复的元素。

@boolOpposite

将布尔值转换为其相反值。

@floatDivide

将字段值除以一个浮点数。

@intAdd

将一个整数加到字段值上。

@intMultiply

将字段值与一个整数相乘。

@intSubtract

从字段值中减去一个整数。

@objectAddEntry

向 JSON 对象中添加一个条目。

@objectFilter

过滤掉对象中的 null 或空元素。

@objectKeepProperties

仅保留 JSON 对象中的特定属性。

@objectRemoveEntry

从 JSON 对象中删除一个条目。

@objectRemoveProperties

从 JSON 对象中删除特定属性。

@setNull

将字段的值设为 null

@strAppend

在字段值字符串的末尾追加一个字符串。

@strLowerCase

将字符串转换为小写。

@strPad

使用另一个字符串将字符串填充至指定长度。

@strPrepend

在字段值字符串的开头插入一个字符串。

@strRegexReplace

执行正则表达式以搜索并替换字符串(参见 PHP 函数 preg_replace 的文档)。

@strRegexReplaceMultiple

执行正则表达式以搜索并替换一组字符串(参见 PHP 函数 preg_replace 的文档)。

@strRepeat

重复一个字符串。

@strReplace

将一个字符串替换为另一个字符串。

@strReplaceMultiple

将一组字符串替换为另一组字符串。

@strReverse

反转字符串。

@strShuffle

随机打乱字符串。

@strStripSlashes

返回去除了反斜杠的字符串。(\' 变为 ',以此类推。) 双反斜杠 (\\) 变为单反斜杠。

@strSubstr

返回字符串的一部分。

@strTitleCase

将字符串转换为标题大小写。

@strTrim

去除字符串开头和结尾的空白(或其他字符)。

@strUpperCase

将字符串转换为大写。

示例

函数字段

虽然我们有 Post.hasComments 字段,但有时可能需要其相反值。与其新建一个 Post.notHasComments 字段(这需要编辑 PHP 代码),不如使用 Field to Input 功能将 hasComments 的值输入到 not 字段中,从而始终在 GraphQL Query 内部完成新值的计算:

{
  posts {
    id
    hasComments
    notHasComments: _not(value: $__hasComments)
  }
}

我们可以多次应用函数字段来执行更复杂的计算,例如根据其他字段的值生成一个 summary 字段:

{
  posts {
    id
    content @remove
    shortContent: _strSubstr(string: $__content, offset: 0, length: 150) @remove
    excerpt @remove
    isExcerptEmpty: _isEmpty(value: $__excerpt) @remove
    summary: _if(
      condition: $__isExcerptEmpty
      then: $__content
      else: $__excerpt
    )
  }
}

结合 HTTP Client 扩展,我们可以动态生成要连接的 API 端点(基于站点上的数据),然后从返回的数据中提取特定字段:

{
  users(
    pagination: { limit: 2 },
    sort: { order: ASC, by: ID }
  ) {
    id
    
    # Dynamically generate endpoint for the user
    endpoint: _arrayJoin(values: [
      "https://newapi.getpop.org/wp-json/wp/v2/users/",
      $__id,
      "?_fields=name,avatar_urls"
    ])
    
    # Retrieve the endpoint data
    endpointData: _sendJSONObjectItemHTTPRequest(input: { url: $__endpoint } )
 
    # Extract specific information
    userAvatar: _objectProperty(
      object: $__endpointData,
      by: {
        path: "avatar_urls.48"
      }
    )
  }
}

...将生成:

{
  "data": {
    "users": [
      {
        "id": 1,
        "endpoint": "https://newapi.getpop.org/wp-json/wp/v2/users/1?_fields=name,avatar_urls",
        "endpointData": {
          "name": "leo",
          "avatar_urls": {
            "24": "https://secure.gravatar.com/avatar/b28085726ee66e49f08be16ad668efd5?s=24&d=mm&r=g",
            "48": "https://secure.gravatar.com/avatar/b28085726ee66e49f08be16ad668efd5?s=48&d=mm&r=g",
            "96": "https://secure.gravatar.com/avatar/b28085726ee66e49f08be16ad668efd5?s=96&d=mm&r=g"
          },
          "_links": {
            "self": [
              {
                "href": "https://newapi.getpop.org/wp-json/wp/v2/users/1"
              }
            ],
            "collection": [
              {
                "href": "https://newapi.getpop.org/wp-json/wp/v2/users"
              }
            ]
          }
        },
        "userAvatar": "https://secure.gravatar.com/avatar/b28085726ee66e49f08be16ad668efd5?s=48&d=mm&r=g"
      },
      {
        "id": 2,
        "endpoint": "https://newapi.getpop.org/wp-json/wp/v2/users/2?_fields=name,avatar_urls",
        "endpointData": {
          "name": "themedemos",
          "avatar_urls": {
            "24": "https://secure.gravatar.com/avatar/7554514b65216821eeacde0fdcd6c6e6?s=24&d=mm&r=g",
            "48": "https://secure.gravatar.com/avatar/7554514b65216821eeacde0fdcd6c6e6?s=48&d=mm&r=g",
            "96": "https://secure.gravatar.com/avatar/7554514b65216821eeacde0fdcd6c6e6?s=96&d=mm&r=g"
          },
          "_links": {
            "self": [
              {
                "href": "https://newapi.getpop.org/wp-json/wp/v2/users/2"
              }
            ],
            "collection": [
              {
                "href": "https://newapi.getpop.org/wp-json/wp/v2/users"
              }
            ]
          }
        },
        "userAvatar": "https://secure.gravatar.com/avatar/7554514b65216821eeacde0fdcd6c6e6?s=48&d=mm&r=g"
      }
    ]
  }
}

函数指令

如果以下 Query:

query {
  posts {
    title
  }
}

...生成了如下结果:

{
  "data": {
    "posts": [
      {
        "title": "Hello world!"
      },
      {
        "title": "lovely weather"
      }
    ]
  }
}

...那么以下 Query:

query {
  posts {
    title @strUpperCase
  }
}

...将生成:

{
  "data": {
    "posts": [
      {
        "title": "HELLO WORLD!"
      },
      {
        "title": "LOVELY WEATHER"
      }
    ]
  }
}