Add Email and StringScalar

Author: spawnia

README.md

@@ -18,6 +18,16 @@ A collection of custom scalar types for usage with https://github.com/webonyx/gr
 You can use the provided Scalars just like any other type in your schema definition.
 Check [SchemaUsageTest](tests/SchemaUsageTest.php) for an example. 
 
+## Simple Scalars
+
+This package comes with a bunch of scalars that are ready-to-use and just work out of the box.
+
+### Email
+
+The Email scalar validates that a given value is a RFC 5321 compliant email.
+
+## Advanced Scalars
+
 ### The Regex Scalar
 
 The `Regex` class allows you to define a custom scalar that validates that the given
@@ -31,9 +41,11 @@ a name and a regular expression and you will receive a ready-to-use custom regex
 
 use MLL\GraphQLScalars\Regex;
 
-$hexValue = Regex::make('HexValue', '/^#?([a-f0-9]{6}|[a-f0-9]{3})$/');
-
-$hexValue instanceof \GraphQL\Type\Definition\ScalarType; // true
+$hexValue = Regex::make(
+    'HexValue',
+    'A hexadecimal color is specified with: #RRGGBB, where RR (red), GG (green) and BB (blue) are hexadecimal integers between 00 and FF specifying the intensity of the color.',
+    '/^#?([a-f0-9]{6}|[a-f0-9]{3})$/'
+);
 ```
 
 You may also define your regex scalar as a class.
@@ -46,9 +58,39 @@ use MLL\GraphQLScalars\Regex;
 // The name is implicitly set through the class name here
 class HexValue extends Regex
 {
+    public $description = 'A hexadecimal color is specified with: #RRGGBB, where RR (red), GG (green) and BB (blue) are hexadecimal integers between 00 and FF specifying the intensity of the color.';
+    
     protected function regex() : string
     {
         return '/^#?([a-f0-9]{6}|[a-f0-9]{3})$/';
     }
 }
 ```
+
+### The StringBase Scalar
+
+The `StringScalar` encapsulate all the boilerplate associated with creating a string-based Scalar type.
+It does the proper string checking for you and let's you focus on the minimal logic that is specific to your use case.
+
+All you have to specify is a function that checks if the given string is valid. Use the factory method
+to generate an instance on the fly.
+
+```php
+<?php
+
+use MLL\GraphQLScalars\StringScalar;
+
+$coolName = StringScalar::make(
+    'CoolName',
+    'A name that is most definitely cool.',
+    function(string $name): bool {
+        return in_array($name, [
+           'Vladar',
+           'Benedikt',
+           'Christopher',
+        ]);
+    }
+);
+```
+
+Or you may simply extend the class, check out the implementation of the [Email](src/Email.php) scalar to see how.

composer.json

@@ -13,7 +13,8 @@
   "require": {
     "php": ">=7.0",
     "webonyx/graphql-php": "^0.12.6",
-    "spatie/regex": "^1.3"
+    "spatie/regex": "^1.3",
+    "egulias/email-validator": "^2.1"
   },
   "require-dev": {
     "phpunit/phpunit": "^6|^7.3"

src/Email.php

@@ -4,67 +4,26 @@
 
 namespace MLL\GraphQLScalars;
 
-use GraphQL\Error\InvariantViolation;
-use GraphQL\Language\AST\Node;
-use GraphQL\Type\Definition\ScalarType;
+use Egulias\EmailValidator\EmailValidator;
+use Egulias\EmailValidator\Validation\RFCValidation;
 
-class Email extends ScalarType
+class Email extends StringScalar
 {
+    /** @var string */
+    public $description = 'A valid RFC 5321 compliant email.';
+    
     /**
-     * Serializes an internal value to include in a response.
+     * Check if the given string is a valid email.
      *
-     * @param string $value
+     * @param string $stringValue
      *
-     * @return string
+     * @return bool
      */
-    public function serialize($value): string
+    protected function isValid(string $stringValue): bool
     {
-        if (!canBeString($value)) {
-            $valueClass = get_class($value);
-
-            throw new InvariantViolation("The given value of class $valueClass can not be serialized.");
-        }
-
-        $stringValue = strval($value);
-
-        if (!$this->matchesRegex($stringValue)) {
-            throw new InvariantViolation("The given string $stringValue did not match the regex {$this->regex()}");
-        }
-
-        return $stringValue;
-    }
-
-    /**
-     * Parses an externally provided value (query variable) to use as an input.
-     *
-     * @param mixed $value
-     *
-     * @return mixed
-     */
-    public function parseValue($value)
-    {
-        // TODO implement validation
-
-        return $value;
-    }
-
-    /**
-     * Parses an externally provided literal value (hardcoded in GraphQL query) to use as an input.
-     *
-     * E.g.
-     * {
-     *   user(email: "[email protected]")
-     * }
-     *
-     * @param Node $valueNode
-     * @param array $variables
-     *
-     * @return mixed
-     */
-    public function parseLiteral($valueNode, array $variables = null)
-    {
-        // TODO implement validation
-
-        return $valueNode->value;
+        return (new EmailValidator)->isValid(
+            $stringValue,
+            new RFCValidation
+        );
     }
 }

src/Regex.php

@@ -19,16 +19,17 @@ abstract class Regex extends ScalarType
      * @return string
      */
     abstract protected function regex(): string;
-
+    
     /**
      * This factory method allows you to create a Regex scalar in a one-liner.
      *
-     * @param string $name
-     * @param string $regex
+     * @param string $name The name that the scalar type will have in the schema.
+     * @param string|null $description A description for the type.
+     * @param string $regex The regular expression that is validated against.
      *
      * @return Regex
      */
-    public static function make(string $name, string $regex): self
+    public static function make(string $name, string $description = null, string $regex): self
     {
         $regexClass = new class() extends Regex {
             /**
@@ -45,6 +46,7 @@ protected function regex(): string
         };
 
         $regexClass->name = $name;
+        $regexClass->description = $description;
         $regexClass->regex = $regex;
 
         return $regexClass;

src/StringScalar.php

@@ -0,0 +1,119 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MLL\GraphQLScalars;
+
+use GraphQL\Error\Error;
+use GraphQL\Error\InvariantViolation;
+use GraphQL\Language\AST\Node;
+use GraphQL\Type\Definition\ScalarType;
+use GraphQL\Utils\Utils;
+
+abstract class StringScalar extends ScalarType
+{
+    /**
+     * Check if the given string is a valid email.
+     *
+     * @param string $stringValue
+     *
+     * @return bool
+     */
+    abstract protected function isValid(string $stringValue): bool;
+    
+    /**
+     * @param string $name The name that the scalar type will have in the schema.
+     * @param string|null $description A description for the type.
+     * @param callable $isValid A function that returns a boolean whether a given string is valid.
+     *
+     * @return StringScalar
+     */
+    public static function make(string $name, string $description = null, callable $isValid): StringScalar
+    {
+        $instance = new class() extends StringScalar {
+            /**
+             * Check if the given string is a valid email.
+             *
+             * @param string $stringValue
+             *
+             * @return bool
+             */
+            protected function isValid(string $stringValue): bool
+            {
+                return call_user_func($this->isValid, $stringValue);
+            }
+        };
+    
+        $instance->name = $name;
+        $instance->description = $description;
+        $instance->isValid = $isValid;
+    
+        return $instance;
+    }
+    
+    /**
+     * Serializes an internal value to include in a response.
+     *
+     * @param string $value
+     *
+     * @return string
+     */
+    public function serialize($value): string
+    {
+        $stringValue = assertString($value, InvariantViolation::class);
+
+        if (!$this->isValid($stringValue)) {
+            throw new InvariantViolation("The given string $stringValue is not a valid {$this->tryInferName()}.");
+        }
+
+        return $stringValue;
+    }
+    
+    /**
+     * Parses an externally provided value (query variable) to use as an input.
+     *
+     * @param mixed $value
+     *
+     * @throws Error
+     *
+     * @return string
+     */
+    public function parseValue($value): string
+    {
+        $stringValue = assertString($value, Error::class);
+        
+        if(!$this->isValid($stringValue)) {
+            $safeValue = Utils::printSafeJson($stringValue);
+            throw new Error("The given string {$safeValue} is not a valid {$this->tryInferName()}.");
+        }
+
+        return $stringValue;
+    }
+    
+    /**
+     * Parses an externally provided literal value (hardcoded in GraphQL query) to use as an input.
+     *
+     * E.g.
+     * {
+     *   user(email: "[email protected]")
+     * }
+     *
+     * @param Node $valueNode
+     * @param array $variables
+     *
+     * @throws Error
+     *
+     * @return string
+     */
+    public function parseLiteral($valueNode, array $variables = null): string
+    {
+        $stringValue = assertStringLiteral($valueNode);
+    
+        if(!$this->isValid($stringValue)) {
+            $safeValue = Utils::printSafeJson($stringValue);
+            throw new Error("The given string {$safeValue} is not a valid {$this->tryInferName()}.", $valueNode);
+        }
+
+        return $stringValue;
+    }
+}

tests/EmailTest.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests;
+
+use GraphQL\Error\Error;
+use GraphQL\Error\InvariantViolation;
+use GraphQL\Language\AST\IntValueNode;
+use GraphQL\Language\AST\NodeKind;
+use GraphQL\Language\AST\StringValueNode;
+use MLL\GraphQLScalars\Email;
+use MLL\GraphQLScalars\Regex;
+
+class EmailTest extends \PHPUnit\Framework\TestCase
+{
+    public function testSerializeThrowsIfUnserializableValueIsGiven()
+    {
+        $this->expectException(InvariantViolation::class);
+        $this->expectExceptionMessageRegExp('/^The given value .* can not be serialized\./');
+
+        (new Email)->serialize(
+            new class() {
+            }
+        );
+    }
+
+    public function testSerializeThrowsIfEmailIsInvalid()
+    {
+        $this->expectException(InvariantViolation::class);
+        $this->expectExceptionMessage('The given string foo is not a valid Email.');
+        
+        (new Email)->serialize('foo');
+    }
+
+    public function testSerializePassesWhenEmailIsInvalid()
+    {
+        $serializedResult = (new Email)->serialize('foo@bar');
+
+        $this->assertSame('foo@bar', $serializedResult);
+    }
+
+    public function testParseValueThrowsIfEmailIsInvalid()
+    {
+        $this->expectException(Error::class);
+        $this->expectExceptionMessage('The given string "foo" is not a valid Email.');
+
+        (new Email)->parseValue('foo');
+    }
+
+    public function testParseValuePassesIfEmailIsValid()
+    {
+        $this->assertSame(
+            'foo@bar',
+            (new Email)->parseValue('foo@bar')
+        );
+    }
+
+    public function testParseLiteralThrowsIfNotValidEmail()
+    {
+        $this->expectException(Error::class);
+        $this->expectExceptionMessage('The given string "foo" is not a valid Email.');
+
+        (new Email)->parseLiteral(new StringValueNode(['value' => 'foo']));
+    }
+    
+    public function testParseLiteralPassesIfEmailIsValid()
+    {
+        $this->assertSame(
+            'foo@bar',
+            (new Email)->parseLiteral(new StringValueNode(['value' => 'foo@bar']))
+        );
+    }
+}