From v3.x to v4.0
Contrary to upgrade a minor version (where the middle number changes) where no difficulty should be encountered, upgrade a major version (where the first number changes) is subject to significant modifications.
Update the libraries
First of all, you have to make sure you are using the last v3.x release.
Spot deprecations
Next, you have to verify you don’t use any deprecated class, interface, method or property. If you have PHPUnit tests, you can easily get the list of deprecation used in your application.
List of deprecations:
Deprecated Packages
The following packages are deprecated. Please install web-token/jwt-library
or web-token/jwt-experimental
instead.
In addtion to the new library or experimental packages, you may need to require third party dependencies such as ext-sodium
, ext-openssl
or .
web-token/jwt-util-ecc
web-token/jwt-key-mgmt
web-token/jwt-core
web-token/jwt-checker
web-token/jwt-console
web-token/jwt-signature
web-token/signature-pack
web-token/jwt-signature-algorithm-*
web-token/jwt-encryption
web-token/encryption-pack
web-token/jwt-encryption-algorithm-*
web-token/jwt-nested-token
PSR-20 Clock
In previous versions, the classes that requires time used the PHP time function directly. It is now required to use a PSR-20 Clock implementation and pass it to the classes.
Jose\Component\Checker\ExpirationTimeChecker
Jose\Component\Checker\IssuedAtChecker
Jose\Component\Checker\NotBeforeChecker
For version 3.2.0+ and the Symfony Bundle, an internal implementation service named jose.internal_clock
existed and is removed.
Simplified Algorithm Manager
Classes Jose\Component\Encryption\JWEBuilder
and Jose\Component\Encryption\JWEDecrypter
no longer need the Key Encryption and Content Encryption Algorithm Managers. You pass only one Algorithm Manager to the contructor.
Version Bumped
All previous major release of the following packages are not supported anymore. Please make sure your platform can use them.
PHP
: 8.3+brick/math
: 0.12+symfony/*
: 7.0+ (expectsymfony/polyfill-*
at version 1.29+)
Upgrade the dependencies and the libraries
Please install this version or a newer one on your platform. Make sure the extensions are also installed. They are namely JSON and MBString. You may also need OpenSSL or Sodium depending on the algorithms you want to use.
It is now time to upgrade the libraries. In your composer.json, change all web-token/*
dependencies from v3.x
to v4.0
. When done, execute composer update
.
You can also update all other dependencies if needed. You can list upgradable libraries by calling composer outdated
. This step is not mandatory, but highly recommended.
Rector is a very nice tool from code upgrade. We highly recommend it.
Last updated