Implement Apollo Federation v2

.gitignore

@@ -1,7 +1,8 @@
+.idea
+.vscode
 composer.phar
 /vendor/
 /node_modules/
 *.cache
 cov.xml
-.idea
-.vscode
+phpunit.xml

README.md

@@ -14,27 +14,28 @@ composer require skillshare/apollo-federation-php
 
 ### Entities
 
-An entity is an object type that you define canonically in one subgraph and can then reference and extend in other subgraphs. It can be defined via the `EntityObjectType` which takes the same configuration as the default `ObjectType` plus a `keyFields` and `__resolveReference` properties. 
+An entity is an object type that you define canonically in one subgraph and can then reference and extend in other subgraphs. It can be defined via the `EntityObjectType` which takes the same configuration as the default `ObjectType` plus a `keys` and `__resolveReference` properties. 
 
 ```php
 use Apollo\Federation\Types\EntityObjectType;
+use GraphQL\Type\Definition\Type;
 
 $userType = new EntityObjectType([
     'name' => 'User',
-    'keyFields' => ['id', 'email'],
+    'keys' => [['fields' => 'id'], ['fields' => 'email']],
     'fields' => [
         'id' => ['type' => Type::int()],
         'email' => ['type' => Type::string()],
         'firstName' => ['type' => Type::string()],
         'lastName' => ['type' => Type::string()]
     ],
-    '__resolveReference' => static function ($ref) {
-        // .. fetch from a data source.
+    '__resolveReference' => function ($ref) {
+        // ... fetch from a data source.
     }
 ]);
 ```
 
-* `keyFields` — defines the entity's primary key, which consists of one or more of the type's. An entity's key cannot include fields that return a union or interface.
+* `keys` — defines the entity's unique keys, which consists of one or more of the fields. An entity's key cannot include fields that return a union or interface.
 
 * `__resolveReference` — resolves the representation of the entity from the provided reference. Subgraphs use representations to reference entities from other subgraphs. A representation requires only an explicit __typename definition and values for the entity's primary key fields.
 
@@ -49,7 +50,7 @@ use Apollo\Federation\Types\EntityRefObjectType;
 
 $userType = new EntityRefObjectType([
     'name' => 'User',
-    'keyFields' => ['id', 'email'],
+    'keys' => [['fields' => 'id', 'resolvable' => false]],
     'fields' => [
         'id' => ['type' => Type::int()],
         'email' => ['type' => Type::string()]
@@ -68,16 +69,12 @@ use Apollo\Federation\Types\EntityRefObjectType;
 
 $userType = new EntityRefObjectType([
     'name' => 'User',
-    'keyFields' => ['id', 'email'],
+    'keys' => [['fields' => 'id', 'resolvable' => false]],
     'fields' => [
         'id' => [
             'type' => Type::int(),
             'isExternal' => true
         ],
-        'email' => [
-            'type' => Type::string(),
-            'isExternal' => true
-        ]
     ]
 ]);
 ```

composer.json

@@ -4,7 +4,7 @@
     "type": "library",
     "license": "MIT",
     "require": {
-        "php": "^7.1||^8.0",
+        "php": "^7.4||^8.0",
         "webonyx/graphql-php": "^0.13.8 || ^14.0"
     },
     "scripts": {

phpunit.xml → phpunit.xml.dist

@@ -1,5 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
-<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd" bootstrap="test/Bootstrap.php">
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="test/Bootstrap.php"
+>
   <coverage>
     <include>
       <directory suffix=".php">./src</directory>

src/Directives.php

@@ -4,62 +4,125 @@
 
 namespace Apollo\Federation;
 
-use Apollo\Federation\Directives\KeyDirective;
 use Apollo\Federation\Directives\ExternalDirective;
+use Apollo\Federation\Directives\InaccessibleDirective;
+use Apollo\Federation\Directives\KeyDirective;
+use Apollo\Federation\Directives\LinkDirective;
+use Apollo\Federation\Directives\OverrideDirective;
 use Apollo\Federation\Directives\ProvidesDirective;
 use Apollo\Federation\Directives\RequiresDirective;
+use Apollo\Federation\Directives\ShareableDirective;
+use Apollo\Federation\Enum\DirectiveEnum;
 
 /**
  * Helper class to get directives for annotating federated entity types.
  */
 class Directives
 {
-    /** @var array */
-    private static $directives;
+    /**
+     * @var array{
+     *     external: ExternalDirective,
+     *     inaccessible: InaccessibleDirective,
+     *     key: KeyDirective,
+     *     link: LinkDirective,
+     *     override: OverrideDirective,
+     *     requires: RequiresDirective,
+     *     provides: ProvidesDirective,
+     *     shareable: ShareableDirective,
+     * }|null
+     */
+    private static ?array $directives = null;
 
     /**
-     * Gets the @key directive
+     * Gets the @key directive.
      */
     public static function key(): KeyDirective
     {
-        return self::getDirectives()['key'];
+        return self::getDirectives()[DirectiveEnum::KEY];
     }
 
     /**
-     * Gets the @external directive
+     * Gets the @external directive.
      */
     public static function external(): ExternalDirective
     {
-        return self::getDirectives()['external'];
+        return self::getDirectives()[DirectiveEnum::EXTERNAL];
+    }
+
+    /**
+     * Gets the @inaccessible directive.
+     */
+    public static function inaccessible(): InaccessibleDirective
+    {
+        return self::getDirectives()[DirectiveEnum::INACCESSIBLE];
+    }
+
+    /**
+     * Gets the `link` directive.
+     */
+    public static function link(): LinkDirective
+    {
+        return self::getDirectives()[DirectiveEnum::LINK];
+    }
+
+    /**
+     * Gets the @override directive.
+     */
+    public static function override(): OverrideDirective
+    {
+        return self::getDirectives()[DirectiveEnum::OVERRIDE];
     }
 
     /**
-     * Gets the @requires directive
+     * Gets the @requires directive.
      */
     public static function requires(): RequiresDirective
     {
-        return self::getDirectives()['requires'];
+        return self::getDirectives()[DirectiveEnum::REQUIRES];
     }
 
     /**
-     * Gets the @provides directive
+     * Gets the @provides directive.
      */
     public static function provides(): ProvidesDirective
     {
-        return self::getDirectives()['provides'];
+        return self::getDirectives()[DirectiveEnum::PROVIDES];
+    }
+
+    /**
+     * Gets the @shareable directive.
+     */
+    public static function shareable(): ShareableDirective
+    {
+        return self::getDirectives()[DirectiveEnum::SHAREABLE];
     }
 
     /**
-     * Gets the directives that can be used on federated entity types
+     * Gets the directives that can be used on federated entity types.
+     *
+     * @return array{
+     *     external: ExternalDirective,
+     *     inaccessible: InaccessibleDirective,
+     *     key: KeyDirective,
+     *     link: LinkDirective,
+     *     override: OverrideDirective,
+     *     requires: RequiresDirective,
+     *     provides: ProvidesDirective,
+     *     shareable: ShareableDirective,
+     * }
      */
     public static function getDirectives(): array
     {
         if (!self::$directives) {
             self::$directives = [
-                'key' => new KeyDirective(),
-                'external' => new ExternalDirective(),
-                'requires' => new RequiresDirective(),
-                'provides' => new ProvidesDirective()
+                DirectiveEnum::EXTERNAL => new ExternalDirective(),
+                DirectiveEnum::INACCESSIBLE => new InaccessibleDirective(),
+                DirectiveEnum::KEY => new KeyDirective(),
+                DirectiveEnum::LINK => new LinkDirective(),
+                DirectiveEnum::OVERRIDE => new OverrideDirective(),
+                DirectiveEnum::REQUIRES => new RequiresDirective(),
+                DirectiveEnum::PROVIDES => new ProvidesDirective(),
+                DirectiveEnum::SHAREABLE => new ShareableDirective(),
             ];
         }
 

src/Directives/ExternalDirective.php

@@ -2,23 +2,24 @@
 
 namespace Apollo\Federation\Directives;
 
-use GraphQL\Type\Definition\Type;
-use GraphQL\Type\Definition\Directive;
-use GraphQL\Type\Definition\FieldArgument;
+use Apollo\Federation\Enum\DirectiveEnum;
 use GraphQL\Language\DirectiveLocation;
+use GraphQL\Type\Definition\Directive;
 
 /**
  * The `@external` directive is used to mark a field as owned by another service. This
  * allows service A to use fields from service B while also knowing at runtime the
  * types of that field.
+ *
+ * @see https://www.apollographql.com/docs/federation/federated-types/federated-directives/#external
  */
 class ExternalDirective extends Directive
 {
     public function __construct()
     {
         parent::__construct([
-            'name' => 'external',
-            'locations' => [DirectiveLocation::FIELD_DEFINITION]
+            'name' => DirectiveEnum::EXTERNAL,
+            'locations' => [DirectiveLocation::FIELD_DEFINITION],
         ]);
     }
 }

src/Directives/InaccessibleDirective.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Apollo\Federation\Directives;
+
+use Apollo\Federation\Enum\DirectiveEnum;
+use GraphQL\Language\DirectiveLocation;
+use GraphQL\Type\Definition\Directive;
+
+/**
+ * The `@inaccessible` directive indicates that a field or type should be omitted from the gateway's API schema,
+ * even if it's also defined in other subgraphs.
+ *
+ * @see https://www.apollographql.com/docs/federation/federated-types/federated-directives/#inaccessible
+ */
+class InaccessibleDirective extends Directive
+{
+    public function __construct()
+    {
+        parent::__construct([
+            'name' => DirectiveEnum::INACCESSIBLE,
+            'locations' => [
+                DirectiveLocation::FIELD_DEFINITION,
+                DirectiveLocation::IFACE,
+                DirectiveLocation::OBJECT,
+                DirectiveLocation::UNION,
+            ],
+        ]);
+    }
+}

src/Directives/KeyDirective.php

@@ -2,28 +2,38 @@
 
 namespace Apollo\Federation\Directives;
 
-use GraphQL\Type\Definition\Type;
+use Apollo\Federation\Enum\DirectiveEnum;
+use GraphQL\Language\DirectiveLocation;
 use GraphQL\Type\Definition\Directive;
 use GraphQL\Type\Definition\FieldArgument;
-use GraphQL\Language\DirectiveLocation;
+use GraphQL\Type\Definition\Type;
 
 /**
  * The `@key` directive is used to indicate a combination of fields that can be used to uniquely
  * identify and fetch an object or interface.
+ *
+ * @see https://www.apollographql.com/docs/federation/federated-types/federated-directives/#key
  */
 class KeyDirective extends Directive
 {
+    public const ARGUMENT_FIELDS = 'fields';
+    public const ARGUMENT_RESOLVABLE = 'resolvable';
+
     public function __construct()
     {
         parent::__construct([
-            'name' => 'key',
+            'name' => DirectiveEnum::KEY,
             'locations' => [DirectiveLocation::OBJECT, DirectiveLocation::IFACE],
             'args' => [
                 new FieldArgument([
-                    'name' => 'fields',
-                    'type' => Type::nonNull(Type::string())
-                ])
-            ]
+                    'name' => self::ARGUMENT_FIELDS,
+                    'type' => Type::nonNull(Type::string()),
+                ]),
+                new FieldArgument([
+                    'name' => self::ARGUMENT_RESOLVABLE,
+                    'type' => Type::boolean(),
+                ]),
+            ],
         ]);
     }
 }