Merge pull request #725 from jaylinski/patch-1

[docs] Clarify change in date-formats

Author: lcobucci

docs/upgrading.md

@@ -131,7 +131,7 @@ There are 4 main differences on the new API:
 
 1. Token configuration methods were renamed
 1. Signature is created via `Builder#getToken()` (instead of `Builder#sign()`)
-1. `DateTimeImmutable` objects are now for the registered claims with dates
+1. `DateTimeImmutable` objects are now used for the registered claims with dates, which are by default encoded as floats with microseconds as precision
 1. Headers should be replicated manually - whenever necessary
 
 Here's the migration:
@@ -178,6 +178,17 @@ Here's the migration:
 +    ->getToken($config->signer(), $config->signingKey());
 ```
 
+#### Date precision
+
+If you want to continue using Unix timestamps, you can use the `withUnixTimestampDates()`-formatter:
+
+```diff
+<?php
+
+-$builder = new Builder());
++$builder = $config->builder(ChainedFormatter::withUnixTimestampDates());
+```
+
 #### Support for multiple audiences
 
 Even though we didn't officially support multiple audiences, it was technically possible to achieve that by manually setting the `aud` claim to an array with multiple strings.