From d6add77540d3133fe4829da6fc863c5cd48efbe2 Mon Sep 17 00:00:00 2001 From: Daniel Tschinder Date: Fri, 9 Feb 2018 17:19:50 +0100 Subject: [PATCH] Add Docs --- UPGRADE.md | 47 ++++++++++++++++++++++++++- docs/reference.md | 54 +++++++++++++++++++++++++------ docs/type-system/type-language.md | 31 ++---------------- 3 files changed, 94 insertions(+), 38 deletions(-) diff --git a/UPGRADE.md b/UPGRADE.md index 50b4518..8126010 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -1,4 +1,49 @@ -## Upgrade v0.10.x > dev-master +## Upgrade v0.11.x > dev-master + +### Breaking: Descriptions in comments are not used as descriptions by default anymore +Descriptions now need to be inside Strings or BlockStrings in order to be picked up as +description. If you want to keep the old behaviour you can supply the option `commentDescriptions` +to BuildSchema::buildAST(), BuildSchema::build() or Printer::doPrint(). + +Here is the official way now to define descriptions in the graphQL language: + +Old: + +```graphql +# Description +type Dog { + ... +} +``` + +New: + +```graphql +"Description" +type Dog { + ... +} + +""" +Long Description +""" +type Dog { + ... +} +``` + +### Breaking: Custom types need to return `Utils::undefined()` or throw on invalid value +As null might be a valid value custom types need to return now `Utils::undefined()` or throw an +Exception inside `parseLiteral()`, `parseValue()` and `serialize()`. + +Returning null from any of these methods will now be treated as valid result. + +### Breaking: TypeConfigDecorator was removed from BuildSchema +TypeConfigDecorator was used as second argument in `BuildSchema::build()` and `BuildSchema::buildAST()` to +enable generated schemas with Unions or Interfaces to be used for resolving. This was fixed in a more +generalised approach so that the TypeConfigDecorator is not needed anymore and can be removed. + +The concrete Types are now resolved based on the `__typename` field. ### Possibly Breaking: AST to array serialization excludes nulls Most users won't be affected. It *may* affect you only if you do your own manipulations diff --git a/docs/reference.md b/docs/reference.md index 7cdc37f..aa033dc 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1352,7 +1352,7 @@ static function setWarningHandler(callable $warningHandler = null) * @api * @param bool|int $suppress */ -static function suppress($suppress = false) +static function suppress($suppress = true) ``` ```php @@ -1367,7 +1367,7 @@ static function suppress($suppress = false) * @api * @param bool|int $enable */ -static function enable($enable = false) +static function enable($enable = true) ``` # GraphQL\Error\ClientAware This interface is used for [default error formatting](error-handling.md). @@ -1697,7 +1697,7 @@ function setPersistentQueryLoader(callable $persistentQueryLoader) * @param bool|int $set * @return $this */ -function setDebug($set = false) +function setDebug($set = true) ``` ```php @@ -1927,13 +1927,19 @@ See [section in docs](type-system/type-language.md) for details. * Given that AST it constructs a GraphQL\Type\Schema. The resulting schema * has no resolve methods, so execution will use default resolvers. * + * Accepts options as a second argument: + * + * - commentDescriptions: + * Provide true to use preceding comments as the description. + * + * * @api * @param DocumentNode $ast - * @param callable $typeConfigDecorator + * @param array $options * @return Schema * @throws Error */ -static function buildAST(GraphQL\Language\AST\DocumentNode $ast, callable $typeConfigDecorator = null) +static function buildAST(GraphQL\Language\AST\DocumentNode $ast, array $options = []) ``` ```php @@ -1943,10 +1949,10 @@ static function buildAST(GraphQL\Language\AST\DocumentNode $ast, callable $typeC * * @api * @param DocumentNode|Source|string $source - * @param callable $typeConfigDecorator + * @param array $options * @return Schema */ -static function build($source, callable $typeConfigDecorator = null) +static function build($source, array $options = []) ``` # GraphQL\Utils\AST Various utilities dealing with AST @@ -2049,6 +2055,32 @@ static function astFromValue($value, GraphQL\Type\Definition\InputType $type) static function valueFromAST($valueNode, GraphQL\Type\Definition\InputType $type, $variables = null) ``` +```php +/** + * Produces a PHP value given a GraphQL Value AST. + * + * Unlike `valueFromAST()`, no type is provided. The resulting JavaScript value + * will reflect the provided GraphQL value AST. + * + * | GraphQL Value | PHP Value | + * | -------------------- | ------------- | + * | Input Object | Assoc Array | + * | List | Array | + * | Boolean | Boolean | + * | String | String | + * | Int / Float | Int / Float | + * | Enum | Mixed | + * | Null | null | + * + * @api + * @param Node $valueNode + * @param array|null $variables + * @return mixed + * @throws \Exception + */ +static function valueFromASTUntyped($valueNode, array $variables = null) +``` + ```php /** * Returns type definition for given AST Type node @@ -2079,11 +2111,15 @@ Given an instance of Schema, prints it in GraphQL type language. **Class Methods:** ```php /** + * Accepts options as a second argument: + * + * - commentDescriptions: + * Provide true to use preceding comments as the description. * @api * @param Schema $schema * @return string */ -static function doPrint(GraphQL\Type\Schema $schema) +static function doPrint(GraphQL\Type\Schema $schema, array $options = []) ``` ```php @@ -2092,5 +2128,5 @@ static function doPrint(GraphQL\Type\Schema $schema) * @param Schema $schema * @return string */ -static function printIntrosepctionSchema(GraphQL\Type\Schema $schema) +static function printIntrosepctionSchema(GraphQL\Type\Schema $schema, array $options = []) ``` diff --git a/docs/type-system/type-language.md b/docs/type-system/type-language.md index bf00dff..57c9960 100644 --- a/docs/type-system/type-language.md +++ b/docs/type-system/type-language.md @@ -33,36 +33,11 @@ $contents = file_get_contents('schema.graphql'); $schema = BuildSchema::build($contents); ``` -By default, such schema is created without any resolvers. As a result, it doesn't support **Interfaces** and **Unions** -because it is impossible to resolve actual implementations during execution. +By default, such schema is created without any resolvers. -Also, we have to rely on [default field resolver](../data-fetching.md#default-field-resolver) and **root value** in +We have to rely on [default field resolver](../data-fetching.md#default-field-resolver) and **root value** in order to execute a query against this schema. -# Defining resolvers -Since 0.10.0 - -In order to enable **Interfaces**, **Unions** and custom field resolvers you can pass the second argument: -**type config decorator** to schema builder. - -It accepts default type config produced by the builder and is expected to add missing options like -[**resolveType**](interfaces.md#configuration-options) for interface types or -[**resolveField**](object-types.md#configuration-options) for object types. - -```php -