Merge pull request thecodingmachine#214 from moufmouf/versioning_docs…

…_4.0

Versioning docs for the 4.0

docs/other_frameworks.md

@@ -24,7 +24,7 @@ In order to bootstrap GraphQLite, you will need:
 Additionally, you will have to route the HTTP requests to the underlying GraphQL library.
 
 GraphQLite relies on the [webonyx/graphql-php](https://webonyx.github.io/graphql-php/) library internally.
-This library plays well with PSR-7 requests and we also provide a [PSR-15 middleware](https://github.com/phps-cans/psr7-middleware-graphql).
+This library plays well with PSR-7 requests and we also provide a [PSR-15 middleware](#psr-15-middleware).
 
 ## Integration
 

website/versioned_docs/version-4.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+---
+id: version-4.0-changelog
+title: Changelog
+sidebar_label: Changelog
+original_id: changelog
+---
+
+## 4.0
+
+This is a complete refactoring from 3.x. While existing annotations are kept compatible, the internals have completely
+changed.
+
+New features:
+
+- You can directly [annotate a PHP interface with `@Type` to make it a GraphQL interface](inheritance-interfaces.md#mapping-interfaces)
+- You can autowire services in resolvers, thanks to the new `@Autowire` annotation
+- Added [user input validation](validation.md) (using the Symfony Validator or the Laravel validator or a custom `@Assertion` annotation
+- Improved security handling:
+ - Unauthorized access to fields can now generate GraphQL errors (rather that schema errors in GraphQLite v3)
+ - Added fine-grained security using the `@Security` annotation. A field can now be [marked accessible or not depending on the context](fine-grained-security.md).
+ For instance, you can restrict access to the field "viewsCount" of the type `BlogPost` only for post that the current user wrote.
+ - You can now inject the current logged user in any query / mutation / field using the `@InjectUser` annotation
+- Performance:
+ - You can inject the [Webonyx query plan in a parameter from a resolver](query_plan.md)
+ - You can use the [dataloader pattern to improve performance drastically via the "prefetchMethod" attribute](prefetch_method.md)
+- Customizable error handling has been added:
+ - You can throw [GraphQL errors](error_handling.md) with `TheCodingMachine\GraphQLite\Exceptions\GraphQLException`
+ - You can specify the HTTP response code to send with a given error, and the errors "extensions" section 
+ - You can throw [many errors in one exception](error_handling.md#many-errors-for-one-exception) with `TheCodingMachine\GraphQLite\Exceptions\GraphQLAggregateException` 
+- You can map [a given PHP class to several PHP input types](input_types.md#declaring-several-input-types-for-the-same-php-class) (a PHP class can have several `@Factory` annotations)
+- You can force input types using `@UseInputType(for="$id", inputType="ID!")`
+- You can extend an input types (just like you could extend an output type in v3) using [the new `@Decorate` annotation](extend_input_type.md)
+- In a factory, you can [exclude some optional parameters from the GraphQL schema](input_types#ignoring-some-parameters)
+
+
+Many extension points have been added 
+
+- Added a "root type mapper" (useful to map scalar types to PHP types or to add custom annotations related to resolvers)
+- Added ["field middlewares"](field_middlewares.md) (useful to add middleware that modify the way GraphQL fields are handled)
+- Added a ["parameter type mapper"](argument_resolving.md) (useful to add customize parameter resolution or add custom annotations related to parameters)
+
+New framework specific features:
+
+Symfony:
+
+- The Symfony bundle now provides a "login" and a "logout" mutation (and also a "me" query)
+
+Laravel:
+
+- [Native integration with the Laravel paginator](laravel-package-advanced.md#support-for-pagination) has been added
+
+Internals:
+
+- The `FieldsBuilder` class has been split in many different services (`FieldsBuilder`, `TypeHandler`, and a 
+ chain of *root type mappers*)
+- The `FieldsBuilderFactory` class has been completely removed.
+- Overall, there is not much in common internally between 4.x and 3.x. 4.x is much more flexible with many more hook points
+ than 3.x. Try it out!

website/versioned_docs/version-4.0/annotations_reference.md

@@ -0,0 +1,244 @@
+---
+id: version-4.0-annotations_reference
+title: Annotations reference
+sidebar_label: Annotations reference
+original_id: annotations_reference
+---
+
+## @Query annotation
+
+The `@Query` annotation is used to declare a GraphQL query.
+
+**Applies on**: controller methods.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+name | *no* | string | The name of the query. If skipped, the name of the method is used instead.
+[outputType](custom_output_types.md) | *no* | string | Forces the GraphQL output type of a query.
+
+## @Mutation annotation
+
+The `@Mutation` annotation is used to declare a GraphQL mutation.
+
+**Applies on**: controller methods.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+name | *no* | string | The name of the mutation. If skipped, the name of the method is used instead.
+[outputType](custom_output_types.md) | *no* | string | Forces the GraphQL output type of a query.
+
+## @Type annotation
+
+The `@Type` annotation is used to declare a GraphQL object type.
+
+**Applies on**: classes.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+class | *no* | string | The targeted class. If no class is passed, the type applies to the current class. The current class is assumed to be an entity. If the "class" attribute is passed, [the class annotated with `@Type` is a service](external_type_declaration.md).
+name | *no* | string | The name of the GraphQL type generated. If not passed, the name of the class is used. If the class ends with "Type", the "Type" suffix is removed
+default | *no* | bool | Defaults to *true*. Whether the targeted PHP class should be mapped by default to this type.
+external | *no* | bool | Whether this is an [external type declaration](external_type_declaration.md) or not. You usually do not need to use this attribute since this value defaults to true if a "class" attribute is set. This is only useful if you are declaring a type with no PHP class mapping using the "name" attribute.
+
+## @ExtendType annotation
+
+The `@ExtendType` annotation is used to add fields to an existing GraphQL object type.
+
+**Applies on**: classes.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+class | see below | string | The targeted class. [The class annotated with `@ExtendType` is a service](extend_type.md).
+name | see below | string | The targeted GraphQL output type.
+
+One and only one of "class" and "name" parameter can be passed at the same time.
+
+## @Field annotation
+
+The `@Field` annotation is used to declare a GraphQL field.
+
+**Applies on**: methods of classes annotated with `@Type` or `@ExtendType`.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+name | *no* | string | The name of the field. If skipped, the name of the method is used instead.
+[outputType](custom_output_types.md) | *no* | string | Forces the GraphQL output type of a query.
+
+## @SourceField annotation
+
+The `@SourceField` annotation is used to declare a GraphQL field.
+
+**Applies on**: classes annotated with `@Type` or `@ExtendType`.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+name | *yes* | string | The name of the field.
+[outputType](custom_output_types.md) | *no* | string | Forces the GraphQL output type of the field. Otherwise, return type is used.
+phpType | *no* | string | The PHP type of the field (as you would write it in a Docblock)
+annotations | *no* | array<Annotations> | A set of annotations that apply to this field. You would typically used a "@Logged" or "@Right" annotation here.
+
+**Note**: `outputType` and `phpType` are mutually exclusive.
+
+## @MagicField annotation
+
+The `@MagicField` annotation is used to declare a GraphQL field that originates from a PHP magic property (using `__get` magic method).
+
+**Applies on**: classes annotated with `@Type` or `@ExtendType`.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+name | *yes* | string | The name of the field.
+[outputType](custom_output_types.md) | *no*(*) | string | The GraphQL output type of the field.
+phpType | *no*(*) | string | The PHP type of the field (as you would write it in a Docblock)
+annotations | *no* | array<Annotations> | A set of annotations that apply to this field. You would typically used a "@Logged" or "@Right" annotation here.
+
+(*) **Note**: `outputType` and `phpType` are mutually exclusive. You MUST provide one of them.
+
+## @Logged annotation
+
+The `@Logged` annotation is used to declare a Query/Mutation/Field is only visible to logged users.
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field`.
+
+This annotation allows no attributes.
+
+## @Right annotation
+
+The `@Right` annotation is used to declare a Query/Mutation/Field is only visible to users with a specific right.
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field`.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+name | *yes* | string | The name of the right.
+
+## @FailWith annotation
+
+The `@FailWith` annotation is used to declare a default value to return in the user is not authorized to see a specific
+query / mutation / field (according to the `@Logged` and `@Right` annotations).
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field` and one of `@Logged` or `@Right` annotations.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+*default* | *yes* | mixed | The value to return if the user is not authorized.
+
+## @HideIfUnauthorized annotation
+
+The `@HideIfUnauthorized` annotation is used to completely hide the query / mutation / field if the user is not authorized
+to access it (according to the `@Logged` and `@Right` annotations).
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field` and one of `@Logged` or `@Right` annotations.
+
+`@HideIfUnauthorized` and `@FailWith` are mutually exclusive.
+
+## @InjectUser annotation
+
+Use the `@InjectUser` annotation to inject an instance of the current user logged in into a parameter of your 
+query / mutation / field.
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field`.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|--------|--------
+*for* | *yes* | string | The name of the PHP parameter
+
+## @Security annotation
+
+The `@Security` annotation can be used to check fin-grained access rights.
+It is very flexible: it allows you to pass an expression that can contains custom logic.
+
+See [the fine grained security page](fine-grained-security.md) for more details.
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field`.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|--------|--------
+*default* | *yes* | string | The security expression
+
+## @Factory annotation
+
+The `@Factory` annotation is used to declare a factory that turns GraphQL input types into objects.
+
+**Applies on**: methods from classes in the "types" namespace.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+name | *no* | string | The name of the input type. If skipped, the name of class returned by the factory is used instead.
+default | *no* | bool | If `true`, this factory will be used by default for its PHP return type. If set to `false`, you must explicitly [reference this factory using the `@Parameter` annotation](https://localhost:3000/docs/input-types#declaring-several-input-types-for-the-same-php-class).
+
+## @UseInputType annotation
+
+Used to override the GraphQL input type of a PHP parameter.
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field` annotation.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+*for* | *yes* | string | The name of the PHP parameter
+*inputType* | *yes* | string | The GraphQL input type to force for this input field
+
+## @Decorate annotation
+
+The `@Decorate` annotation is used [to extend/modify/decorate an input type declared with the `@Factory` annotation](extend_input_type.md).
+
+**Applies on**: methods from classes in the "types" namespace.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+name | *yes* | string | The GraphQL input type name extended by this decorator.
+
+## @Autowire annotation
+
+[Resolves a PHP parameter from the container](autowiring.md).
+
+Useful to inject services directly into `@Field` method arguments.
+
+**Applies on**: methods annotated with `@Query`, `@Mutation` or `@Field` annotation.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+*for* | *yes* | string | The name of the PHP parameter
+*identifier* | *no* | string | The identifier of the service to fetch. This is optional. Please avoid using this attribute as this leads to a "service locator" anti-pattern.
+
+## @HideParameter annotation
+
+Removes [an argument from the GraphQL schema](input_types.md#ignoring_some_parameters).
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+*for* | *yes* | string | The name of the PHP parameter to hide
+
+
+## @Validate annotation
+
+<div class="alert alert-info">This annotation is only available in the GraphQLite Laravel package</div>
+
+[Validates a user input in Laravel](laravel-package-advanced.md).
+
+**Applies on**: methods annotated with `@Query`, `@Mutation`, `@Field`, `@Factory` or `@Decorator` annotation.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+*for* | *yes* | string | The name of the PHP parameter
+*rule* | *yes | string | Laravel validation rules
+
+Sample:
+
+```
+@Validate(for="$email", rule="email|unique:users")
+```
+
+## @Assertion annotation
+
+[Validates a user input](validation.md).
+
+The `@Assertion` annotation is available in the *thecodingmachine/graphqlite-symfony-validator-bridge* third party package.
+It is available out of the box if you use the Symfony bundle.
+
+**Applies on**: methods annotated with `@Query`, `@Mutation`, `@Field`, `@Factory` or `@Decorator` annotation.
+
+Attribute | Compulsory | Type | Definition
+---------------|------------|------|--------
+*for* | *yes* | string | The name of the PHP parameter
+*constraint* | *yes | annotation | One (or many) Symfony validation annotations.