|
| 1 | +# Upgrading from 4.x to 5.0 |
| 2 | + |
| 3 | +5.0 reworks the bundle's exception hierarchy onto a marker interface and |
| 4 | +bumps the `itk-dev/openid-connect` requirement to `^5.0`. Runtime behaviour |
| 5 | +is unchanged — this document covers the consumer-visible API changes you'll |
| 6 | +need to adjust catch blocks for. |
| 7 | + |
| 8 | +See the architecture decision in |
| 9 | +[docs/adr/001-marker-interface-exception-hierarchy.md](docs/adr/001-marker-interface-exception-hierarchy.md). |
| 10 | + |
| 11 | +## Catch the marker interface, not the abstract |
| 12 | + |
| 13 | +Concrete bundle exceptions no longer extend |
| 14 | +`\ItkDev\OpenIdConnectBundle\Exception\ItkOpenIdConnectBundleException`. |
| 15 | +Existing catches against the abstract will not match anything thrown by |
| 16 | +5.0+ code: |
| 17 | + |
| 18 | +```diff |
| 19 | +- } catch (\ItkDev\OpenIdConnectBundle\Exception\ItkOpenIdConnectBundleException $e) { |
| 20 | ++ } catch (\ItkDev\OpenIdConnectBundle\Exception\OpenIdConnectBundleExceptionInterface $e) { |
| 21 | +``` |
| 22 | + |
| 23 | +The abstract class is kept through the 5.x line as a `@deprecated` alias |
| 24 | +that still implements the marker; removal is scheduled for 6.0. |
| 25 | + |
| 26 | +`OpenIdConnectBundleExceptionInterface` **extends** the upstream library's |
| 27 | +`\ItkDev\OpenIdConnect\Exception\OpenIdConnectExceptionInterface`, so a |
| 28 | +single catch handles failures from both packages: |
| 29 | + |
| 30 | +```php |
| 31 | +try { |
| 32 | + $claims = $this->validateClaims($request); |
| 33 | +} catch (\ItkDev\OpenIdConnect\Exception\OpenIdConnectExceptionInterface $e) { |
| 34 | + // catches both library- and bundle-thrown OIDC failures |
| 35 | +} |
| 36 | +``` |
| 37 | + |
| 38 | +## Catch on SPL types still works |
| 39 | + |
| 40 | +Each concrete now extends the SPL type that best fits its failure category, |
| 41 | +so catches at the SPL level continue to match: |
| 42 | + |
| 43 | +| Concrete | Parent | When it fires | |
| 44 | +| --- | --- | --- | |
| 45 | +| `InvalidProviderException` | `\InvalidArgumentException` | Unknown provider key requested from the manager | |
| 46 | +| `UsernameDoesNotExistException` | `\InvalidArgumentException` | CLI login resolved a token to no username | |
| 47 | +| `CacheException` | `\RuntimeException` | PSR-6 cache layer failed during CLI login token handling | |
| 48 | +| `TokenNotFoundException` | `\RuntimeException` | CLI login token not found in the cache | |
| 49 | +| `UserDoesNotExistException` | `\RuntimeException` | Configured user provider has no matching user | |
| 50 | + |
| 51 | +For example, code catching the raw `\InvalidArgumentException` around a |
| 52 | +provider lookup keeps working, because `InvalidProviderException` still |
| 53 | +extends it: |
| 54 | + |
| 55 | +```php |
| 56 | +try { |
| 57 | + $provider = $providerManager->getProvider($key); |
| 58 | +} catch (\InvalidArgumentException $e) { // still catches in 5.0 |
| 59 | + // ... |
| 60 | +} |
| 61 | +``` |
| 62 | + |
| 63 | +## Update the dependency constraint |
| 64 | + |
| 65 | +If your application pins the bundle, bump it to `^5.0`. The bundle now |
| 66 | +requires `itk-dev/openid-connect:^5.0`; review that library's |
| 67 | +[UPGRADE-5.0.md](https://github.com/itk-dev/openid-connect/blob/main/UPGRADE-5.0.md) |
| 68 | +for its own contract changes (it reworks the same exception hierarchy and |
| 69 | +tightens several IdP-payload validations). |
| 70 | + |
| 71 | +## Framework-boundary exceptions are unchanged |
| 72 | + |
| 73 | +`LoginController` still ships Symfony `HttpException` subclasses |
| 74 | +(`NotFoundHttpException` for an unknown provider → 404, |
| 75 | +`ServiceUnavailableHttpException` for an unreachable IdP / cache failure → |
| 76 | +503), and authenticators still throw `AuthenticationException`. These are a |
| 77 | +documented carve-out from the wrap-at-boundary rule and did not change in |
| 78 | +5.0; the OIDC cause remains chained via `$previous`. |
0 commit comments