Add upgrade guide for version 8

upgrade-guide.md

@@ -6,6 +6,56 @@ permalink: /upgrade-guide/
 
 # Upgrade Guide
 
+## 7.x.x → 8.x.x
+
+Version `8.x.x` requires PHP 7.1.0 or higher. This is a major release so contains some breaking changes from version
+`7.x.x`. Please read the following notes carefully when upgrading your system.
+
+### Public Key Code Exchange (PKCE)
+The `enableCodeExchangeProof` flag has been removed from the AuthCodeGrant. This flag was used to determine whether PKCE
+checks should be enabled on the server. The server will now initiate PKCE checks whenever a client sends a _code
+challenge_.
+
+The _AuthCodeGrant_ has a new flag, `requireCodeChallengeForPublicClients`. The flag defaults to true and requires all
+public clients to provide a PKCE code challenge when requesting an access token. If you want to disable this, you can
+call the function `disableRequireCodeChallengeForPublicClients()` which will set the flag to false. For security, we 
+recommend you keep this flag set to true.
+
+#### Client Entity Interface
+To identify a client as public or confidential, version 8 of the server calls the new `isConfidential()` function. You
+will need to update your client entity implementation to include this new function.
+
+### Invalid User for Password Grant
+If a user cannot be validated when using the _Password Grant_, the server will return an `invalid_grant` error.
+Previously the server returned an `invalid_credentials` error. You should notify or update any clients that might expect
+ to receive an `invalid_credentials` error in this scenario.
+
+### Crypt Trait
+The `encrypt()` and `decrypt()` functions now throw exceptions if no encryption key is set when running these functions.
+
+### Access Tokens
+Access tokens no longer have the function `convertToJwt()`. This has been replaced with the magic method `__toString()`.
+
+### DateTimeImmutable
+Most instances of `DateTime` have been replaced with `DateTimeImmutable` instances. You should change your code to use
+`DateTimeImmutable` where the library has made these changes. The affected interfaces and their functions are as
+follows:
+
+#### RefreshTokenEntityInterface
+- `getExpiryDateTime()`
+- `setExpiryDateTime()`
+
+#### TokenInterface
+- `getExpiryDateTime()`
+- `setExpiryDateTime()`
+
+Please note that any traits that implement these interfaces have also been updated.
+
+### JWT Headers
+
+We no longer set the JTI claim in the header of an issued JWT. The JTI claim is now only present in the payload of the 
+JWT. If any of your code retrieved the JTI from the header, you must update it to retrieve this claim from the payload.
+
 ## 6.x.x → 7.x.x
 
 Version `7.x.x` requires PHP 7.0.0 or higher. This version is not backwards compatible with version `6.x.x` of the library.
@@ -14,10 +64,10 @@ The interface for `getClientEntity()` in the `clientRepositoryInterface` has cha
 
 ```patch
   public function getClientEntity(
-      $clientIdentifier, 
+      $clientIdentifier,
 -     $grantType,
 +     $grantType = null,
-      $clientSecret = null, 
+      $clientSecret = null,
       $mustValidateSecret = true
   );
 ```
@@ -44,4 +94,4 @@ To generate an encryption key for the `AuthorizationServer` run the following co
 
 ~~~ shell
 php -r 'echo base64_encode(random_bytes(32)), PHP_EOL;'
-~~~
+~~~