Version 6.0 Release (#483)

* Update docs for #466

* Upgrade to use node 18 for CI

* Upgrade Docusaurus

* Added README for docs development and versioning

* Versioned docs for 6.0 release

.github/workflows/doc_generation.yml

@@ -24,7 +24,7 @@ jobs:
  - name: "Setup NodeJS"
  uses: actions/setup-node@v3
  with:
- node-version: '14.x'
+ node-version: '18.x'
 
  - name: "Yarn install"
  run: yarn install

website/README

@@ -0,0 +1,32 @@
+# GraphQLite Website
+
+The GraphQLite website is primarily a documentation site for GraphQLite. It's built on the Docusaurus framework, and is hosted on [GitHub](https://graphqlite.thecodingmachine.io/).
+
+More details on using Docusaurus can be found in the [official documentation](https://docusaurus.io/docs/docs-introduction).
+
+*This documentation could use further updating.*
+
+## Developing and Testing
+
+All code changes, aside from errors in previous documentation, should be done in the `docs` directory. The `package.json` file outlines available commands you can use for starting the server, building the docs, etc.
+
+- `npm run build` *(Transpiles/builds `docs` into `build` directory)*
+- `npm run start` *(Starts the local npm server)*
+
+## Versioning
+
+Firstly, doc versions are cached in the `versioned_docs` directory. Meanwhile, the "Next" version, as represented on the website, is the current `master` branch of the `docs` dir. A list of the versions available is actually managed by the `versions.json` file, regardless of the `versioned_docs` directory.
+
+The [versioning section of the Docusaurus documentation](https://docusaurus.io/docs/versioning) covers this is more detail, but the following is related to our specific implementation:
+
+### Steps to Create and Deploy a new Version
+
+*All command paths are relative to the `website` directory. Ensure that you have `./node_modules/.bin` added to your path.*
+
+1. Firstly, we need to tag a new version, which will cache a copy of the documentation in the `versioned_docs` directory, update the `versioned_sidebars`, and update the `versions.json` file.
+
+ ```bash
+ $ docusaurus docs:version 1.1
+ ```
+ *Be sure to include the X.X in the version, not just X.*
+2. Technically, you're done, just commit these changes and the CI workflow will deploy when merged into `master`.

website/docs/input-types.mdx

@@ -128,6 +128,9 @@ Using the `#[Input]` attribute, we can transform the `Location` class, in the ex
 class Location
 {
 
+ #[Field]
+ private ?string $name = null;
+
  #[Field]
  private float $latitude;
 
@@ -140,6 +143,11 @@ class Location
  $this->longitude = $longitude;
  }
 
+ public function setName(string $name): void
+ {
+ $this->name = $name;
+ }
+
  public function getLatitude(): float
  {
  return $this->latitude;
@@ -162,6 +170,12 @@ class Location
 class Location
 {
 
+ /**
+ * @Field
+ * @var string|null
+ */
+ private ?string $name = null;
+
  /**
  * @Field
  * @var float
@@ -180,6 +194,11 @@ class Location
  $this->longitude = $longitude;
  }
 
+ public function setName(string $name): void
+ {
+ $this->name = $name;
+ }
+
  public function getLatitude(): float
  {
  return $this->latitude;
@@ -199,13 +218,13 @@ Now if you call the `getCities` query, from the controller in the first example,
 
 There are some important things to notice:
 
-- The `@Field` annotation is recognized only on properties for Input Type, not methods.
+- The `@Field` annotation is recognized on properties for Input Type, as well as setters.
 - There are 3 ways for fields to be resolved:
  - Via constructor if corresponding properties are mentioned as parameters with the same names - exactly as in the example above.
  - If properties are public, they will be just set without any additional effort - no constructor required.
- - For private or protected properties implemented, a public setter is required (if they are not set via the constructor). For example `setLatitude(float $latitude)`.
+ - For private or protected properties implemented, a public setter is required (if they are not set via the constructor). For example `setLatitude(float $latitude)`. You can also put the `@Field` annotation on the setter, instead of the property, allowing you to have use many other attributes (`Security`, `Right`, `Autowire`, etc.).
 - For validation of these Input Types, see the [Custom InputType Validation section](validation#custom-inputtype-validation).
-- We advise using the `#[Input]` attribute on DTO style input type objects and not directly on your model objects. Using it on your model objects can cause coupling in undesirable ways.
+- It's advised to use the `#[Input]` attribute on DTO style input type objects and not directly on your model objects. Using it on your model objects can cause coupling in undesirable ways.
 
 ### Multiple Input Types from the same class
 
@@ -239,8 +258,14 @@ class UserInput
  #[Field(for: 'UpdateUserInput', inputType: 'String')]
  public string $password;
 
+ protected ?int $age;
+
+
  #[Field]
- public ?int $age;
+ public function setAge(?int $age): void
+ {
+ $this->age = $age;
+ }
 }
 ```
 
@@ -274,11 +299,17 @@ class UserInput
  */
  public $password;
 
+ /** @var int|null */
+ protected $age;
+
  /**
  * @Field()
- * @var int|null
+ * @param int|null $age
  */
- public $age;
+ public function setAge(?int $age): void
+ {
+ $this->age = $age;
+ }
 }
 ```
 

website/docusaurus.config.js

@@ -43,6 +43,9 @@ module.exports={
  "blog": {},
  "theme": {
  "customCss": "/src/css/custom.css"
+ },
+ "gtag": {
+ "trackingID": "UA-10196481-8"
  }
  }
  ]
@@ -82,13 +85,10 @@ module.exports={
  "href": 'https://github.com/thecodingmachine/graphqlite',
  }
  },
- "algolia": {
- "apiKey": "8fcce617e281864dc03c68d17f6206db",
- "indexName": "graphqlite_thecodingmachine",
- "algoliaOptions": {}
- },
- "gtag": {
- "trackingID": "UA-10196481-8"
- }
+ // "algolia": {
+ // "apiKey": "8fcce617e281864dc03c68d17f6206db",
+ // "indexName": "graphqlite_thecodingmachine",
+ // "algoliaOptions": {}
+ // }
  }
 }

website/package.json

@@ -6,13 +6,12 @@
  "swizzle": "docusaurus swizzle",
  "deploy": "bin/deploy-github"
  },
- "devDependencies": {
- },
+ "devDependencies": {},
  "dependencies": {
- "@docusaurus/core": "2.0.0-beta.14",
- "@docusaurus/preset-classic": "2.0.0-beta.14",
+ "@docusaurus/core": "2.0.0-beta.21",
+ "@docusaurus/preset-classic": "2.0.0-beta.21",
  "clsx": "^1.1.1",
- "mdx-mermaid": "^1.1.0",
+ "mdx-mermaid": "^1.2.3",
  "mermaid": "^8.12.0",
  "react": "^17.0.1",
  "react-dom": "^17.0.1"

website/versioned_docs/version-6.0/CHANGELOG.md

@@ -0,0 +1,123 @@
+---
+id: changelog
+title: Changelog
+sidebar_label: Changelog
+---
+
+## 5.0.0
+
+#### Dependencies:
+
+- Upgraded to using version 14.9 of [webonyx/graphql-php](https://github.com/webonyx/graphql-php)
+
+## 4.3.0
+
+#### Breaking change:
+
+- The method `setAnnotationCacheDir($directory)` has been removed from the `SchemaFactory`. The annotation
+ cache will use your `Psr\SimpleCache\CacheInterface` compliant cache handler set through the `SchemaFactory`
+ constructor.
+
+#### Minor changes:
+
+- Removed dependency for doctrine/cache and unified some of the cache layers following a PSR interface.
+- Cleaned up some of the documentation in an attempt to get things accurate with versioned releases.
+
+## 4.2.0
+
+#### Breaking change:
+
+The method signature for `toGraphQLOutputType` and `toGraphQLInputType` have been changed to the following:
+
+```php
+/**
+ * @param \ReflectionMethod|\ReflectionProperty $reflector
+ */
+public function toGraphQLOutputType(Type $type, ?OutputType $subType, $reflector, DocBlock $docBlockObj): OutputType;
+
+/**
+ * @param \ReflectionMethod|\ReflectionProperty $reflector
+ */
+public function toGraphQLInputType(Type $type, ?InputType $subType, string $argumentName, $reflector, DocBlock $docBlockObj): InputType;
+```
+
+#### New features:
+
+- [@Input](annotations-reference.md#input-annotation) annotation is introduced as an alternative to `@Factory`. Now GraphQL input type can be created in the same manner as `@Type` in combination with `@Field` - [example](input-types.mdx#input-attribute).
+- New attributes has been added to [@Field](annotations-reference.md#field-annotation) annotation: `for`, `inputType` and `description`.
+- The following annotations now can be applied to class properties directly: `@Field`, `@Logged`, `@Right`, `@FailWith`, `@HideIfUnauthorized` and `@Security`.
+
+## 4.1.0
+
+#### Breaking change:
+
+There is one breaking change introduced in the minor version (this was important to allow PHP 8 compatibility).
+
+- The **ecodev/graphql-upload** package (used to get support for file uploads in GraphQL input types) is now a "recommended" dependency only.
+ If you are using GraphQL file uploads, you need to add `ecodev/graphql-upload` to your `composer.json`.
+
+#### New features:
+
+- All annotations can now be accessed as PHP 8 attributes
+- The `@deprecated` annotation in your PHP code translates into deprecated fields in your GraphQL schema
+- You can now specify the GraphQL name of the Enum types you define
+- Added the possibility to inject pure Webonyx objects in GraphQLite schema
+
+#### Minor changes:
+
+- Migrated from `zend/diactoros` to `laminas/diactoros`
+- Making the annotation cache directory configurable
+
+#### Miscellaneous:
+
+- Migrated from Travis to Github actions
+
+
+## 4.0.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.mdx#mapping-interfaces)
+- You can autowire services in resolvers, thanks to the new `@Autowire` annotation
+- Added [user input validation](validation.mdx) (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.mdx).
+ 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.mdx)
+ - You can use the [dataloader pattern to improve performance drastically via the "prefetchMethod" attribute](prefetch-method.mdx)
+- Customizable error handling has been added:
+ - You can throw [many errors in one exception](error-handling.mdx#many-errors-for-one-exception) with `TheCodingMachine\GraphQLite\Exceptions\GraphQLAggregateException`
+- 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.mdx)
+- 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.mdx#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!