From 7c0aa4ceec8704f30adb5b48587a9f5d0298206d Mon Sep 17 00:00:00 2001 From: vladar Date: Fri, 25 Nov 2016 16:37:00 +0700 Subject: [PATCH] Better docs and comments on breaks and deprecations for 8.0 --- UPGRADE.md | 51 +++++++++++++-------------- src/Error/FormattedError.php | 2 +- src/Executor/Executor.php | 4 +-- src/Executor/Values.php | 2 +- src/Type/Definition/Directive.php | 2 +- src/Type/Definition/FieldArgument.php | 1 - src/Type/Definition/ResolveInfo.php | 2 +- 7 files changed, 30 insertions(+), 34 deletions(-) diff --git a/UPGRADE.md b/UPGRADE.md index 72ac3c1..7c0bbd4 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -1,22 +1,14 @@ # Upgrade ## Upgrade v0.7.x > v0.8.x - -### AST node classes -AST node classes were renamed to disambiguate with types. e.g.: - -``` -GraphQL\Language\AST\Field -> GraphQL\Language\AST\FieldNode -GraphQL\Language\AST\OjbectValue -> GraphQL\Language\AST\OjbectValueNode -``` -etc. - -Node kind constants were extracted from `GraphQL\Language\AST\Node` to `GraphQL\Language\AST\NodeKind` +All of those changes apply to those who extends various parts of this library. +If you only use the library and don't try to extend it - everything should work without breaks. -### Custom directives handling +### Breaking: Custom directives handling When passing custom directives to schema, default directives (like `@skip` and `@include`) -are not added to schema automatically anymore. If you need them - add them explicitly with your other directives +are not added to schema automatically anymore. If you need them - add them explicitly with +your other directives. Before the change: ```php @@ -34,26 +26,31 @@ $schema = new Schema([ ]); ``` -### Protected property and method naming -In order to unify coding style, leading underscores were removed from all private and protected properties -and methods. +### Breaking: Schema protected property and methods visibility +Most of the `protected` properties and methods of `GraphQL\Schema` were changed to `private`. +Please use public interface instead. + +### Breaking: Node kind constants +Node kind constants were extracted from `GraphQL\Language\AST\Node` to +separate class `GraphQL\Language\AST\NodeKind` + +### Non-breaking: AST node classes renamed +AST node classes were renamed to disambiguate with types. e.g.: -Example before the change: -```php -GraphQL\Schema::$_queryType; ``` - -Correct usage after the change: -```php -GraphQL\Schema::$queryType; +GraphQL\Language\AST\Field -> GraphQL\Language\AST\FieldNode +GraphQL\Language\AST\OjbectValue -> GraphQL\Language\AST\OjbectValueNode ``` +etc. -So if you rely on any protected properties or methods of any GraphQL class, make sure to -delete leading underscores. +Old names are still available via `class_alias` defined in `src/deprecated.php`. +This file is included automatically when using composer autoloading. ### Deprecations -There are also several deprecations which still work, but trigger `E_USER_DEPRECATED` -when used. +There are several deprecations which still work, but trigger `E_USER_DEPRECATED` when used. + +For example `GraphQL\Executor\Executor::setDefaultResolveFn()` is renamed to `setDefaultResolver()` +but still works with old name. ## Upgrade v0.6.x > v0.7.x diff --git a/src/Error/FormattedError.php b/src/Error/FormattedError.php index 68b42ea..7326a36 100644 --- a/src/Error/FormattedError.php +++ b/src/Error/FormattedError.php @@ -14,7 +14,7 @@ use GraphQL\Utils; class FormattedError { /** - * @deprecated since 2016-10-21 + * @deprecated as of 8.0 * @param $error * @param SourceLocation[] $locations * @return array diff --git a/src/Executor/Executor.php b/src/Executor/Executor.php index 4f58f4d..0d87840 100644 --- a/src/Executor/Executor.php +++ b/src/Executor/Executor.php @@ -894,7 +894,7 @@ class Executor } /** - * @deprecated as of 19.11.2016 + * @deprecated as of 8.0 */ public static function defaultResolveFn($source, $args, $context, ResolveInfo $info) { @@ -903,7 +903,7 @@ class Executor } /** - * @deprecated as of 19.11.2016 + * @deprecated as of 8.0 */ public static function setDefaultResolveFn($fn) { diff --git a/src/Executor/Values.php b/src/Executor/Values.php index a5d4b4a..2e12ce0 100644 --- a/src/Executor/Values.php +++ b/src/Executor/Values.php @@ -162,7 +162,7 @@ class Values } /** - * @deprecated Moved to Utils\AST::valueFromAST + * @deprecated as of 8.0 (Moved to Utils\AST::valueFromAST) * * @param $valueNode * @param InputType $type diff --git a/src/Type/Definition/Directive.php b/src/Type/Definition/Directive.php index 6951a35..dda85c7 100644 --- a/src/Type/Definition/Directive.php +++ b/src/Type/Definition/Directive.php @@ -19,7 +19,7 @@ class Directive /** * @var array - * @deprecated as of 8.0 (use constants directly) + * @deprecated as of 8.0 (use DirectiveLocation constants directly) */ public static $directiveLocations = [ // Operations: diff --git a/src/Type/Definition/FieldArgument.php b/src/Type/Definition/FieldArgument.php index 73b066f..f3719b1 100644 --- a/src/Type/Definition/FieldArgument.php +++ b/src/Type/Definition/FieldArgument.php @@ -89,7 +89,6 @@ class FieldArgument /** * @return InputType - * @deprecated in favor of setting 'fields' as closure per objectType vs on individual field/argument level */ public function getType() { diff --git a/src/Type/Definition/ResolveInfo.php b/src/Type/Definition/ResolveInfo.php index 737d95a..c104335 100644 --- a/src/Type/Definition/ResolveInfo.php +++ b/src/Type/Definition/ResolveInfo.php @@ -24,7 +24,7 @@ class ResolveInfo /** * @var FieldNode[] - * @deprecated Renamed to $fieldNodes as of 19.11.2016, will be removed after several releases + * @deprecated as of 8.0 (Renamed to $fieldNodes) */ public $fieldASTs;