Repository files navigation

This package provides classes and utilities forwebonyx/graphql-php for creatingfederated GraphQL subgraphs in PHP to be consumed by the Apollo Gateway.

⚠️IMPORTANT: This package is still in active development and it might introduce breaking changes.

Via composer:

composer require skillshare/apollo-federation-php

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 theEntityObjectType which takes the same configuration as the defaultObjectType plus akeyFields and__resolveReference properties.

useApollo\Federation\Types\EntityObjectType;$userType =newEntityObjectType(['name' =>'User','keyFields' => ['id','email'],'fields' => ['id' => ['type' => Type::int()],'email' => ['type' => Type::string()],'firstName' => ['type' => Type::string()],'lastName' => ['type' => Type::string()]    ],'__resolveReference' =>staticfunction ($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.

• __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.

For more detail on entities,see the official docs.

A subgraph can reference entities from another subgraph by defining a stub including just enough information to know how to interact with the referenced entity. Entity references are created via theEntityRefObjectType which takes the same configuration as the baseEntityObjectType.

useApollo\Federation\Types\EntityRefObjectType;$userType =newEntityRefObjectType(['name' =>'User','keyFields' => ['id','email'],'fields' => ['id' => ['type' => Type::int()],'email' => ['type' => Type::string()]    ]]);

For more detail on entity references,see the official docs.

A subgraph can add fields to an entity that's defined in another subgraph. This is called extending the entity. When a subgraph extends an entity, the entity's originating subgraph is not aware of the added fields. Only the extending subgraph (along with the gateway) knows about these fields.

useApollo\Federation\Types\EntityRefObjectType;$userType =newEntityRefObjectType(['name' =>'User','keyFields' => ['id','email'],'fields' => ['id' => ['type' => Type::int(),'isExternal' =>true        ],'email' => ['type' => Type::string(),'isExternal' =>true        ]    ]]);

The subgraph can extend using the following configuration properties:

• isExternal — marks 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.

• provides — used to annotate the expected returned fieldset from a field on a base type that is guaranteed to be selectable by the gateway.

• requires — used to annotate the required input fieldset from a base type for a resolver. It is used to develop a query plan where the required fields may not be needed by the client, but the service may need additional information from other services.

TheFederatedSchema class extends from the baseGraphQL\Schema class and augments a schema configuration using entity types and federated field annotations with Apollo Federation metadata.See the docs for more info.

useGraphQL\GraphQL;useApollo\Federation\FederatedSchema;$schema =newFederatedSchema($config);$query ='query GetServiceSDL { _service { sdl } }';$result = GraphQL::executeQuery($schema,$query);

The config parameter for theFederatedSchema object is entirely compatible with theSchema config argument. On top of this, we support the following optional parameters:

1. entityTypes - the entity types (which extendEntityObjectType) which will form the_Entity type on the federated schema. If not provided, the Schema will scan theQuery type tree for all types extendingEntityObjectType.

Documentation in this project include content quoted directly from theApollo official documentation to reduce redundancy.