Removed

• Removed the dependency on Lcobbuci's Clock to avoid conflicts with other clock implemenations in user land (PR #1505)

Removed

• Removed the dependency on Lcobbuci's Clock to avoid conflicts with other clock implemenations in user land (PR #1505)

9.4.1 Latest

Latest

Compare

Choose a tag to compare

Changed

• Authorization requests are now checked for the required response_type parameter before we determine which grant type is being used (PR #1507)
• User ID is now passed to the finalizeScopes method for the Refresh Grant (PR #1414)

Removed

• Removed support for PHP 8.1 (PR #1500)

Changed

• Authorization requests are now checked for the required response_type parameter before we determine which grant type is being used (PR #1507)
• User ID is now passed to the finalizeScopes method for the Refresh Grant (PR #1414)

Removed

• Removed support for PHP 8.1 (PR #1500)

9.4.0

Compare

Choose a tag to compare

Added

• Added sensitive parameter to avoid sensitive data being included in stack traces (PR #1483)
• Support for PHP 8.5 (PR #1492)

Fixed

• Made the Bearer header case insensitive to match the specs correctly (PR #1491)

Added

• Added sensitive parameter to avoid sensitive data being included in stack traces (PR #1483)
• Support for PHP 8.5 (PR #1492)

Fixed

• Made the Bearer header case insensitive to match the specs correctly (PR #1491)

9.3.0

Compare

Choose a tag to compare

Added

• Added a new function to the provided ClientTrait, supportsGrantType to allow the auth server to issue the response unauthorized_client when applicable (PR #1420)

Fixed

• Fix a bug on setting interval visibility of device authorization grant (PR #1410)
• Fix a bug where the new poll date were not persisted when slow_down error happens, because the exception is thrown before calling persistDeviceCode. (PR #1410)
• Fix a bug where slow_down error response may have been returned even after the user has completed the auth flow (already approved / denied the request). (PR #1410)
• Clients only validated for Refresh, Device Code, and Password grants if the client is confidential (PR #1420)
• Emit RequestAccessTokenEvent and RequestRefreshTokenEvent events instead of the general RequestEvent event when an access / refresh token is issued using device authorization grant. (PR #1467)

Added

• Added a new function to the provided ClientTrait, supportsGrantType to allow the auth server to issue the response unauthorized_client when applicable (PR #1420)

Fixed

• Fix a bug on setting interval visibility of device authorization grant (PR #1410)
• Fix a bug where the new poll date were not persisted when slow_down error happens, because the exception is thrown before calling persistDeviceCode. (PR #1410)
• Fix a bug where slow_down error response may have been returned even after the user has completed the auth flow (already approved / denied the request). (PR #1410)
• Clients only validated for Refresh, Device Code, and Password grants if the client is confidential (PR #1420)
• Emit RequestAccessTokenEvent and RequestRefreshTokenEvent events instead of the general RequestEvent event when an access / refresh token is issued using device authorization grant. (PR #1467)

Changed

• Key permission checks ignored on Windows regardless of userland choice as cannot be run successfully on this OS (PR #1447)

9.2.0

Compare

Choose a tag to compare

Added

• Support for PHP 8.4 (PR #1454)

Fixed

• In the Auth Code grant, when requesting an access token with an invalid auth code, we now respond with an invalid_grant error instead of invalid_request (PR #1433)
• Fixed spec compliance issue where device access token request was mistakenly expecting to receive scopes in the request (PR #1412)
• Refresh tokens pre version 9 might have had user IDs set as ints which meant they were incorrectly rejected. We now cast these values to strings to allow old refresh tokens (PR #1436)

Added

• Support for PHP 8.4 (PR #1454)

Fixed

• In the Auth Code grant, when requesting an access token with an invalid auth code, we now respond with an invalid_grant error instead of invalid_request (PR #1433)
• Fixed spec compliance issue where device access token request was mistakenly expecting to receive scopes in the request (PR #1412)
• Refresh tokens pre version 9 might have had user IDs set as ints which meant they were incorrectly rejected. We now cast these values to strings to allow old refresh tokens (PR #1436)

9.1.0

Compare

Choose a tag to compare

Fixed

• Auto-generated event emitter is now persisted. Previously, a new emitter was generated every time (PR #1428)
• Fixed bug where you could not omit a redirect uri even if one had not been specified during the auth request (PR #1428)
• Fixed bug where "state" parameter wasn't present on invalid_scope error response and wasn't on fragment part of access_denied redirect URI on Implicit grant (PR #1298)
• Fixed bug where disabling refresh token revocation via revokeRefreshTokens(false) unintentionally disables issuing new refresh token (PR #1449)

Fixed

• Auto-generated event emitter is now persisted. Previously, a new emitter was generated every time (PR #1428)
• Fixed bug where you could not omit a redirect uri even if one had not been specified during the auth request (PR #1428)
• Fixed bug where "state" parameter wasn't present on invalid_scope error response and wasn't on fragment part of access_denied redirect URI on Implicit grant (PR #1298)
• Fixed bug where disabling refresh token revocation via revokeRefreshTokens(false) unintentionally disables issuing new refresh token (PR #1449)

9.0.1

Compare

Choose a tag to compare

Added

• Device Authorization Grant added (PR #1074)
• GrantTypeInterface has a new function, revokeRefreshTokens() for enabling or disabling refresh tokens after use (PR #1375)
• A CryptKeyInterface to allow developers to change the CryptKey implementation with greater ease (PR #1044)
• The authorization server can now finalize scopes when a client uses a refresh token (PR #1094)
• An AuthorizationRequestInterface to make it easier to extend the AuthorizationRequest (PR #1110)
• Added function getKeyContents() to the CryptKeyInterface (PR #1375)

Fixed

• Basic authorization is now case insensitive (PR #1403)
• If a refresh token has expired, been revoked, cannot be decrypted, or does not belong to the correct client, the server will now issue an invalid_grant error and a HTTP 400 response. In previous versions the server incorrectly issued an invalid_request and HTTP 401 response (PR #1042) (PR #1082)

Changed

• All interfaces now specify types for all params and return values. Strict typing enforced (PR #1074)
• Request parameters are now parsed into strings to use internally in the library (PR #1402)
• Authorization Request objects are now created through the factory method, createAuthorizationRequest() (PR #1111)
• Changed parameters for finalizeScopes() to allow a reference to an auth code ID (PR #1112)
• AccessTokenEntityInterface now requires the implementation of toString() instead of the magic method __toString() (PR #1395)

Removed

• Removed message property from OAuthException HTTP response. Now just use error_description as per the OAuth 2 spec (PR #1375)

Added

• Device Authorization Grant added (PR #1074)
• GrantTypeInterface has a new function, revokeRefreshTokens() for enabling or disabling refresh tokens after use (PR #1375)
• A CryptKeyInterface to allow developers to change the CryptKey implementation with greater ease (PR #1044)
• The authorization server can now finalize scopes when a client uses a refresh token (PR #1094)
• An AuthorizationRequestInterface to make it easier to extend the AuthorizationRequest (PR #1110)
• Added function getKeyContents() to the CryptKeyInterface (PR #1375)

Fixed

• Basic authorization is now case insensitive (PR #1403)
• If a refresh token has expired, been revoked, cannot be decrypted, or does not belong to the correct client, the server will now issue an invalid_grant error and a HTTP 400 response. In previous versions the server incorrectly issued an invalid_request and HTTP 401 response (PR #1042) (PR #1082)

Changed

• All interfaces now specify types for all params and return values. Strict typing enforced (PR #1074)
• Request parameters are now parsed into strings to use internally in the library (PR #1402)
• Authorization Request objects are now created through the factory method, createAuthorizationRequest() (PR #1111)
• Changed parameters for finalizeScopes() to allow a reference to an auth code ID (PR #1112)
• AccessTokenEntityInterface now requires the implementation of toString() instead of the magic method __toString() (PR #1395)

Removed

• Removed message property from OAuthException HTTP response. Now just use error_description as per the OAuth 2 spec (PR #1375)

9.0.0

Compare

Choose a tag to compare

Added

• Device Authorization Grant added (PR #1074)
• GrantTypeInterface has a new function, revokeRefreshTokens() for enabling or disabling refresh tokens after use (PR #1375)
• A CryptKeyInterface to allow developers to change the CryptKey implementation with greater ease (PR #1044)
• The authorization server can now finalize scopes when a client uses a refresh token (PR #1094)
• An AuthorizationRequestInterface to make it easier to extend the AuthorizationRequest (PR #1110)
• Added function getKeyContents() to the CryptKeyInterface (PR #1375)

Fixed

• If a refresh token has expired, been revoked, cannot be decrypted, or does not belong to the correct client, the server will now issue an invalid_grant error and a HTTP 400 response. In previous versions the server incorrectly issued an invalid_request and HTTP 401 response (PR #1042) (PR #1082)

Changed

• Authorization Request objects are now created through the factory method, createAuthorizationRequest() (PR #1111)
• Changed parameters for finalizeScopes() to allow a reference to an auth code ID (PR #1112)
• AccessTokenEntityInterface now requires the implementation of toString() instead of the magic method __toString() (PR #1395)

Removed

• Removed message property from OAuthException HTTP response. Now just use error_description as per the OAuth 2 spec (PR #1375)

Added

• Device Authorization Grant added (PR #1074)
• GrantTypeInterface has a new function, revokeRefreshTokens() for enabling or disabling refresh tokens after use (PR #1375)
• A CryptKeyInterface to allow developers to change the CryptKey implementation with greater ease (PR #1044)
• The authorization server can now finalize scopes when a client uses a refresh token (PR #1094)
• An AuthorizationRequestInterface to make it easier to extend the AuthorizationRequest (PR #1110)
• Added function getKeyContents() to the CryptKeyInterface (PR #1375)

Fixed

• If a refresh token has expired, been revoked, cannot be decrypted, or does not belong to the correct client, the server will now issue an invalid_grant error and a HTTP 400 response. In previous versions the server incorrectly issued an invalid_request and HTTP 401 response (PR #1042) (PR #1082)

Changed

• Authorization Request objects are now created through the factory method, createAuthorizationRequest() (PR #1111)
• Changed parameters for finalizeScopes() to allow a reference to an auth code ID (PR #1112)
• AccessTokenEntityInterface now requires the implementation of toString() instead of the magic method __toString() (PR #1395)

Removed

• Removed message property from OAuthException HTTP response. Now just use error_description as per the OAuth 2 spec (PR #1375)

9.0.0-RC1 Pre-release

Pre-release

Compare

Choose a tag to compare

Fixed

• PHP 8.4 deprecation notices fixed (PR #1466)

8.5.5

Compare

Choose a tag to compare

Added

• Support for league/uri ^7.0 (PR #1367)

Security

• If a key string is provided to the CryptKey constructor with an invalid passphrase, the LogicException message generated will expose the given key. The key is no longer leaked via this exception (PR #1353)

Changed

• Bumped the versions for laminas/diactoros and psr/http-message to support PSR-7 v2.0 (PR #1339)

Fixed

• Fixed PHP version constraints and lcobucci/clock version constraint to support PHP 8.1 (PR #1336)

Added

• Support for PHP 8.1 and 8.2 (PR #1333)

Removed

• Support PHP 7.2, 7.3, and 7.4 (PR #1333)

Fixed

• PHP 8.4 deprecation notices fixed (PR #1466)

8.4.3

Compare

Choose a tag to compare

Fixed

• Fix deprecation notices for PHP 8.x (PR #1329)

Added

• You can now set a leeway for time drift between servers when validating a JWT (PR #1304)

Security

• Access token requests that contain a code_verifier but are not bound to a code_challenge will be rejected to prevent a PKCE downgrade attack (PR #1326)

Fixed

• Use LooseValidAt instead of StrictValidAt so that users aren't forced to use claims such as NBF in their JWT tokens (PR #1312)

Fixed

• Use InMemory::plainText('empty', 'empty') instead of InMemory::plainText('') to avoid new empty string exception thrown by lcobucci/jwt (PR #1282)

Fixed

• Server previously rejected valid uris with custom schemes. Now use league/uri for parsing to accept all valid uris (PR #1274)

Security

• Removed the use of LocalFileReference() in lcobucci/jwt. Function deprecated as per GHSA-7322-jrq4-x5hf (PR #1249)

Changed

• Conditionally support the StrictValidAt() method in lcobucci/jwt so we can use version 4.1.x or greater of the library (PR #1236)
• When providing invalid credentials, the library now responds with the error message The user credentials were incorrect (PR #1230)
• Keys are always stored in memory now and are not written to a file in the /tmp directory (PR #1180)
• The regex for matching the bearer token has been simplified (PR #1238)

Fixed

• Revert check on clientID. We will no longer require this to be a string (PR #1233)

Added

• The server will now validate redirect uris according to rfc8252 (PR #1203)
• Events emitted now include the refresh token and access token payloads (PR #1211)
• Use the revokeRefreshTokens() function to decide whether refresh tokens are revoked or not upon use (PR #1189)

Changed

• Keys are now validated using openssl_pkey_get_private() and openssl_pkey_get_public() instead of regex matching (PR #1215)

Fixed

• The server will now only recognise and handle an authorization header if the value of the header is non-empty. This is to circumvent issues where some common frameworks set this header even if no value is present (PR #1170)
• Added type validation for redirect uri, client ID, client secret, scopes, auth code, state, username, and password inputs (PR #1210)
• Allow scope "0" to be used. Previously this was removed from a request because it failed an empty() check (PR #1181)

Fixed

• Reverted the enforcement of at least one redirect_uri for a client. This change has instead been moved to version 9 (PR #1169)

Added

• Re-added support for PHP 7.2 (PR #1165, #1167)

Fixed

• Fix issue where the private key passphrase isn't correctly passed to JWT library (PR #1164)

Fixed

• If you have a password on your private key, it is now passed correctly to the JWT configuration object. (PR #1159)

Added

• Add a getRedirectUri function to the OAuthServerException class (PR #1123)
• Support for PHP 8.0 (PR #1146)

Removed

• Removed support for PHP 7.2 (PR #1146)

Fixed

• Fix typo in parameter hint. code_challenged changed to code_challenge. Thrown by Auth Code Grant when the code challenge does not match the regex. (PR #1130)
• Undefined offset was returned when no client redirect URI was set. Now throw an invalidClient exception if no redirect URI is set against a client (PR #1140)

Fixed

• If you provide a valid redirect_uri with the auth code grant and an invalid scope, the server will use the given redirect_uri instead of the default client redirect uri (PR #1126)

Added

• Added support for PHP 7.4 (PR #1075)

Changed

• If an error is encountered when running preg_match() to validate an RSA key, the server will now throw a RuntimeException (PR #1047)
• Replaced deprecated methods with recommended ones when using Lcobucci\JWT\Builder to build a JWT token. (PR #1060)
• When storing a key, we no longer touch the file before writing it as this is an unnecessary step (PR #1064)
• Prefix native PHP functions in namespaces with backslashes for micro-optimisations (PR #1071)

Removed

• Support for PHP 7.1 (PR #1075)

Fixed

• Clients are now explicitly prevented from using the Client Credentials grant unless they are confidential to conform with the OAuth2 spec (PR #1035)
• Abstract method getIdentifier() added to AccessTokenTrait. The trait cannot be used without the getIdentifier() method being defined (PR #1051)
• An exception is now thrown if a refresh token is accidentally sent in place of an authorization code when using the Auth Code Grant (PR #1057)
• Can now send access token request without being forced to specify a redirect URI (PR #1096)
• In the BearerTokenValidator, if an implementation is using PDO, there is a possibility that a RuntimeException will be thrown when checking if an access token is revoked. This scenario no longer incorrectly issues an exception with a hint mentioning an issue with JSON decoding. (PR #1107)

Added

• Flag, requireCodeChallengeForPublicClients, used to reject public clients that do not provide a code challenge for the Auth Code Grant; use AuthCodeGrant::disableRequireCodeCallengeForPublicClients() to turn off this requirement (PR #938)
• Public clients can now use the Auth Code Grant (PR #938)
• isConfidential getter added to ClientEntity to identify type of client (PR #938)
• Function validateClient() added to validate clients which was previously performed by the getClientEntity() function (PR #938)
• Add a new function to the AbstractGrant class called getClientEntityOrFail(). This is a wrapper around the getClientEntity() function that ensures we emit and throw an exception if the repo doesn't return a client entity. (PR #1010)

Changed

• Replace convertToJWT() interface with a more generic __toString() to improve extensibility; AccessTokenEntityInterface now requires setPrivateKey(CryptKey $privateKey) so __toString() has everything it needs to work (PR #874)
• The invalidClient() function accepts a PSR-7 compliant $serverRequest argument to avoid accessing the $_SERVER global variable and improve testing (PR #899)
• issueAccessToken() in the Abstract Grant no longer sets access token client, user ID or scopes. These values should already have been set when calling getNewToken() (PR #919)
• No longer need to enable PKCE with enableCodeExchangeProof flag. Any client sending a code challenge will initiate PKCE checks. (PR #938)
• Function getClientEntity() no longer performs client validation (PR #938)
• Password Grant now returns an invalid_grant error instead of invalid_credentials if a user cannot be validated (PR #967)
• Use DateTimeImmutable() instead of DateTime(), time() instead of (new DateTime())->getTimeStamp(), and DateTime::getTimeStamp() instead of DateTime::format('U') (PR #963)

Removed

• enableCodeExchangeProof flag (PR #938)
• Support for PHP 7.0 (PR #1014)
• Remove JTI claim from JWT header (PR #1031)

Changed

• RefreshTokenRepository can now return null, allowing refresh tokens to be optional. (PR #649)

Added

• Added error_description to the error payload to improve standards compliance. The contents of this are copied from the existing message value. (PR #1006)

Deprecated

• Error payload will not issue message value in the next major release (PR #1006)

Fixed

• Revert setting keys on response type to be inside getResponseType() function instead of AuthorizationServer constructor (PR #969)

Fixed

• Fix issue with previous release where interface had changed for the AuthorizationServer. Reverted to the previous interface while maintaining functionality changes (PR #970)

Changed

• Moved the finalizeScopes() call from validateAuthorizationRequest method to the completeAuthorizationRequest method so it is called just before the access token is issued (PR #923)

Added

• Added a ScopeTrait to provide an implementation for jsonSerialize (PR #952)
• Ability to nest exceptions (PR #965)

Fixed

• Fix issue where AuthorizationServer is not stateless as ResponseType could store state of a previous request (PR #960)

Changed

• Added newvalidateRedirectUri method AbstractGrant to remove three instances of code duplication (PR #912)
• Allow 640 as a crypt key file permission (PR #917)

Added

• Function hasRedirect() added to OAuthServerException (PR #703)

Fixed

• Catch and handle BadMethodCallException from the verify() method of the JWT token in the validateAuthorization method (PR #904)

Fixed

• No longer set a WWW-Authenticate header for invalid clients if the client did not send an Authorization header in the original request (PR #902)

Changed

• Changed hint for unsupportedGrantType exception so it no longer references the grant type parameter which isn't always expected (PR #893)
• Upgrade PHPStan checks to level 7 (PR #856)

Added

• Added event emitters for issued access and refresh tokens (PR #860)
• Can now use Defuse\Crypto\Key for encryption/decryption of keys which is faster than the Cryto class (PR #812)

Removed

• Remove paragone/random_compat from dependencies

Added

• Use PHPStan for static analysis of code (PR #848)
• Enforce stricter static analysis checks and upgrade library dependencies (PR #852)
• Provide PHPStan coverage for tests and update PHPUnit (PR #849)
• Get and set methods for OAuth Server Exception payloads. Allow implementer to specify the JSON encode options (PR #719)

Changed

• ClientRepository interface will now accept null for the Grant type to improve extensibility options (PR #607)
• Do not issue an error if key file permissions are 400 or 440 (PR #839)
• Skip key file creation if the file already exists (PR #845)
• Change changelog format and update readme

Removed

• Support for PHP 5.6
• Support for version 5.x and 6.x of the library

Fixed

• PKCE implementation (PR #744)
• Set correct redirect URI when validating scopes (PR #840)
• S256 code challenege method (PR #842)
• Accept RSA key with CRLF line endings (PR #805)

• Removed check on empty scopes

• Changed the token type issued by the Implicit Grant to be Bearer instead of bearer. (PR #724)
• Replaced call to array_key_exists() with the faster isset() on the Implicit Grant. (PR #749)
• Allow specification of query delimiter character in the Password Grant (PR #801)
• Add Zend Diactoros library dependency to examples (PR #678)
• Can set default scope for the authorization endpoint. If no scope is passed during an authorization request, the default scope will be used if set. If not, the server will issue an invalid scope exception (PR #811)
• Added validation for redirect URIs on the authorization end point to ensure exactly one redirection URI has been passed (PR #573)

• An invalid refresh token that can't be decrypted now returns a HTTP 401 error instead of HTTP 400 (Issue #759)
• Removed chmod from CryptKey and add toggle to disable checking (Issue #776)
• Fixes invalid code challenge method payload key name (Issue #777)

To address feedback from the security release the following change has been made:

• If an RSA key cannot be chmod'ed to 600 then it will now throw a E_USER_NOTICE instead of an exception.

• Breaking change: The AuthorizationServer constructor now expects an encryption key string instead of a public key
• Remove support for HHVM
• Remove support for PHP 5.5

• Fixed multiple security vulnerabilities as a result of a security audit paid for by the Mozilla Secure Open Source Fund. All users of this library are encouraged to update as soon as possible to this version or version 6.0 or greater.
• It is recommended on each AuthorizationServer instance you set the setEncryptionKey(). This will result in stronger encryption being used. If this method is not set messages will be sent to the defined error handling routines (using error_log). Please see the examples and documentation for examples.
• TravisCI now tests PHP 7.1 (Issue #671)
• Fix middleware example fatal error (Issue #682)
• Fix typo in the first README sentence (Issue #690)
• Corrected DateInterval from 1 min to 1 month (Issue #709)

• Fixed WWW-Authenticate header (Issue #669)
• Increase the recommended RSA key length from 1024 to 2048 bits (Issue #668)

• Fixed finalizeScopes call (Issue #650)

• Improved test suite (Issue #614)
• Updated docblocks (Issue #616)
• Replace array_shift with foreach loop (Issue #621)
• Allow easy addition of custom fields to Bearer token response (Issue #624)
• Key file auto-generation from string (Issue #625)

• Implemented RFC7636 (Issue #574)
• Unify middleware exception responses (Issue #578)
• Updated examples (Issue #589)
• Ensure state is in access denied redirect (Issue #597)
• Remove redundant isExpired() method from entity interfaces and traits (Issue #600)
• Added a check for unique access token constraint violation (Issue #601)
• Look at Authorization header directly for HTTP Basic auth checks (Issue #604)
• Added catch Runtime exception when parsing JWT string (Issue #605)
• Allow paragonie/random_compat 2.x (Issue #606)
• Added indigophp/hash-compat to Composer suggestions and require-dev for PHP 5.5 support

• Fix hints in PasswordGrant (Issue #560)
• Add meaning of Resource owner to terminology.md (Issue #561)
• Use constant for event name instead of explicit string (Issue #563)
• Remove unused request property (Issue #564)
• Correct wrong phpdoc (Issue #569)
• Fixed typo in exception string (Issue #570)

• state parameter is now correctly returned after implicit grant authorization
• Small code and docblock improvements

• Fixes an issue (#550) whereby it was unclear whether or not to validate a client's secret during a request.

Version 5 is a complete code rewrite.

• Renamed Server class to AuthorizationServer
• Added ResourceServer class
• Run unit tests again PHP 5.5.9 as it's the minimum supported version
• Enable PHPUnit 5.0 support
• Improved examples and documentation
• Make it clearer that the implicit grant doesn't support refresh tokens
• Improved refresh token validation errors
• Fixed refresh token expiry date

• Allow multiple client redirect URIs (Issue #511)
• Remove unused mac token interface (Issue #503)
• Handle RSA key passphrase (Issue #502)
• Remove access token repository from response types (Issue #501)
• Remove unnecessary methods from entity interfaces (Issue #490)
• Ensure incoming JWT hasn't expired (Issue #509)
• Fix client identifier passed where user identifier is expected (Issue #498)
• Removed built-in entities; added traits to for quick re-use (Issue #504)
• Redirect uri is required only if the "redirect_uri" parameter was included in the authorization request (Issue #514)
• Removed templating for auth code and implicit grants (Issue #499)

Version 5 is a complete code rewrite.

• JWT support
• PSR-7 support
• Improved exception errors
• Replace all occurrences of the term "Storage" with "Repository"
• Simplify repositories
• Entities conform to interfaces and use traits
• Auth code grant updated
  • Allow support for public clients
  • Add support for #439
• Client credentials grant updated
• Password grant updated
  • Allow support for public clients
• Refresh token grant updated
• Implement Implicit grant
• Bearer token output type
• Remove MAC token output type
• Authorization server rewrite
• Resource server class moved to PSR-7 middleware
• Tests
• Much much better documentation