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

Author: oojacoboo

.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!