Document that CustomScalarType requires static callables (#905)

Author: spawnia

docs/type-definitions/scalars.md

@@ -1,9 +1,9 @@
 # Built-in Scalar Types
-GraphQL specification describes several built-in scalar types. In **graphql-php** they are 
-exposed as static methods of [`GraphQL\Type\Definition\Type`](../class-reference.md#graphqltypedefinitiontype) class:
+
+The GraphQL specification describes several built-in scalar types. In **graphql-php** they are 
+exposed as static methods of the class [`GraphQL\Type\Definition\Type`](../class-reference.md#graphqltypedefinitiontype):
 
 ```php
-<?php
 use GraphQL\Type\Definition\Type;
 
 // Built-in Scalar types:
@@ -13,34 +13,33 @@ Type::float();   // Float type
 Type::boolean(); // Boolean type
 Type::id();      // ID type
 ```
-Those methods return instances of `GraphQL\Type\Definition\ScalarType` (actually one of subclasses).
+
+Those methods return instances of a subclass of `GraphQL\Type\Definition\ScalarType`.
 Use them directly in type definitions or wrapped in a type registry (see [lazy loading of types](../schema-definition.md#lazy-loading-of-types)). 
 
 # Writing Custom Scalar Types
+
 In addition to built-in scalars, you can define your own scalar types with additional validation. 
 Typical examples of such types are **Email**, **Date**, **Url**, etc.
 
-In order to implement your own type, you must understand how scalars are presented in GraphQL.
-GraphQL deals with scalars in following cases:
+In order to implement your own type, you must understand how scalars are handled in GraphQL.
+GraphQL deals with scalars in the following cases:
 
-1. When converting **internal representation** of value returned by your app (e.g. stored in a database 
-or hardcoded in the source code) to **serialized** representation included in the response.
+1. Convert the **internal representation** of a value, returned by your app (e.g. stored in a database 
+or hardcoded in the source code), to a **serialized representation** included in the response.
 
-2. When converting **input value** passed by a client in variables along with GraphQL query to 
-**internal representation** of your app.
+2. Convert an **input value**, passed by a client in variables along with a GraphQL query, to 
+its **internal representation** used in your application.
 
-3. When converting **input literal value** hardcoded in GraphQL query (e.g. field argument value) to 
-the **internal representation** of your app.
+3. Convert an **input literal value**, hardcoded in a GraphQL query (e.g. field argument value), to 
+its **internal representation** used in your application.
 
-Those cases are covered by methods `serialize`, `parseValue` and `parseLiteral` of abstract `ScalarType` 
-class respectively.
+Those cases are covered by the methods `serialize`, `parseValue` and `parseLiteral` of the
+abstract class `ScalarType` respectively.
 
 Here is an example of a simple **Email** type:
 
 ```php
-<?php
-namespace MyApp;
-
 use GraphQL\Error\Error;
 use GraphQL\Error\InvariantViolation;
 use GraphQL\Language\AST\StringValueNode;
@@ -53,62 +52,35 @@ class EmailType extends ScalarType
     // (suffix "Type" will be dropped)
     public $name = 'Email';
 
-    /**
-     * Serializes an internal value to include in a response.
-     *
-     * @param string $value
-     * @return string
-     */
     public function serialize($value)
     {
-        // Assuming internal representation of email is always correct:
-        return $value;
-        
-        // If it might be incorrect and you want to make sure that only correct values are included
-        // in response - use following line instead:
-        // if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
-        //     throw new InvariantViolation("Could not serialize following value as email: " . Utils::printSafe($value));
-        // }
-        // return $this->parseValue($value);
+        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
+            throw new InvariantViolation("Could not serialize following value as email: " . Utils::printSafe($value));
+        }
+
+        return $this->parseValue($value);
     }
 
-    /**
-     * Parses an externally provided value (query variable) to use as an input
-     *
-     * @param mixed $value
-     * @return mixed
-     */
     public function parseValue($value)
     {
         if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
             throw new Error("Cannot represent following value as email: " . Utils::printSafeJson($value));
         }
+
         return $value;
     }
 
-    /**
-     * Parses an externally provided literal value (hardcoded in GraphQL query) to use as an input.
-     * 
-     * E.g. 
-     * {
-     *   user(email: "[email protected]") 
-     * }
-     *
-     * @param \GraphQL\Language\AST\Node $valueNode
-     * @param array|null $variables
-     * @return string
-     * @throws Error
-     */
     public function parseLiteral(Node $valueNode, ?array $variables = null)
     {
-        // Note: throwing GraphQL\Error\Error vs \UnexpectedValueException to benefit from GraphQL
-        // error location in query:
+        // Throw GraphQL\Error\Error vs \UnexpectedValueException to locate the error in the query
         if (!$valueNode instanceof StringValueNode) {
             throw new Error('Query error: Can only parse strings got: ' . $valueNode->kind, [$valueNode]);
         }
+
         if (!filter_var($valueNode->value, FILTER_VALIDATE_EMAIL)) {
             throw new Error("Not a valid email", [$valueNode]);
         }
+
         return $valueNode->value;
     }
 }
@@ -117,13 +89,15 @@ class EmailType extends ScalarType
 Or with inline style:
 
 ```php
-<?php
 use GraphQL\Type\Definition\CustomScalarType;
 
 $emailType = new CustomScalarType([
     'name' => 'Email',
-    'serialize' => function($value) {/* See function body above */},
-    'parseValue' => function($value) {/* See function body above */},
-    'parseLiteral' => function($valueNode, array $variables = null) {/* See function body above */},
+    'serialize' => static function($value) {/* See function body above */},
+    'parseValue' => static function($value) {/* See function body above */},
+    'parseLiteral' => static function(Node $valueNode, ?array $variables = null) {/* See function body above */},
 ]);
 ```
+
+Keep in mind the passed functions will be called statically, so a passed in `callable`
+such as `[Foo::class, 'bar']` should only reference static class methods.

tests/Type/DefinitionTest.php

@@ -33,44 +33,31 @@ class DefinitionTest extends TestCase
 {
     use ArraySubsetAsserts;
 
-    /** @var ObjectType */
-    public $blogImage;
+    public ObjectType $blogImage;
 
-    /** @var ObjectType */
-    public $blogArticle;
+    public ObjectType $blogArticle;
 
-    /** @var ObjectType */
-    public $blogAuthor;
+    public ObjectType $blogAuthor;
 
-    /** @var ObjectType */
-    public $blogMutation;
+    public ObjectType $blogMutation;
 
-    /** @var ObjectType */
-    public $blogQuery;
+    public ObjectType $blogQuery;
 
-    /** @var ObjectType */
-    public $blogSubscription;
+    public ObjectType $blogSubscription;
 
-    /** @var ObjectType */
-    public $objectType;
+    public ObjectType $objectType;
 
-    /** @var ObjectType */
-    public $objectWithIsTypeOf;
+    public ObjectType $objectWithIsTypeOf;
 
-    /** @var InterfaceType */
-    public $interfaceType;
+    public InterfaceType $interfaceType;
 
-    /** @var UnionType */
-    public $unionType;
+    public UnionType $unionType;
 
-    /** @var EnumType */
-    public $enumType;
+    public EnumType $enumType;
 
-    /** @var InputObjectType */
-    public $inputObjectType;
+    public InputObjectType $inputObjectType;
 
-    /** @var CustomScalarType */
-    public $scalarType;
+    public CustomScalarType $scalarType;
 
     public function setUp(): void
     {