Marker-interface exception contract (5.0 — BREAKING)

[turegjorup]

Summary

The public exception contract becomes a marker interface — \ItkDev\OpenIdConnect\Exception\OpenIdConnectExceptionInterface extends \Throwable — instead of the abstract ItkOpenIdConnectException class. Every concrete exception is re-parented to the SPL type that best describes its failure category and implements the marker.

See the new "Exception handling" subsection in README.md for the consumer-facing migration guide.

What changes

Hierarchy

• New: OpenIdConnectExceptionInterface (marker, extends \Throwable).
• New: ConfigurationException extends \InvalidArgumentException (replaces raw \InvalidArgumentException thrown from the constructor when a required option is missing).
• Re-parented: every concrete now extends the right SPL type — see the parent-class table below.
• Deprecated: ItkOpenIdConnectException abstract class. Kept for 5.x with @deprecated; still implements the marker. Concretes no longer extend it, so existing catch (ItkOpenIdConnectException $e) blocks will not match anything thrown by 5.0+ code. This is the BC break behind the MAJOR bump.

Concrete	New SPL parent	Category
BadUrlException, IllegalSchemeException, MissingParameterException	\LogicException	Programmer / config bug
ConfigurationException, NegativeCacheDurationException, NegativeLeewayException	\InvalidArgumentException	Invalid input
CacheException, HttpException, JsonException, DecodeException, KeyException, CodeException, ValidationException, ClaimsException	\RuntimeException	Runtime / transient

HttpException keeps its second interface Psr\Http\Client\ClientExceptionInterface so PSR-18-aware consumers can still catch on the standard PSR marker.

Boundary fixes in OpenIdConfigurationProvider

• Constructor wraps raw \InvalidArgumentException as ConfigurationException (still extends \InvalidArgumentException, so existing catches at that level keep matching).
• getIdToken narrows its boundary catch from \Exception to IdentityProviderException|ClientExceptionInterface|\JsonException. Failures from getConfiguration (e.g. CacheException during the token-endpoint lookup) now propagate as their own concrete type rather than being re-wrapped as CodeException.
• All public-method @throws PHPDoc now references OpenIdConnectExceptionInterface instead of the deprecated abstract.

Test additions

• tests/Exception/ExceptionHierarchyTest.php locks the contract: every concrete is verified to implement the marker, extend the correct SPL parent, and be catchable via catch (OpenIdConnectExceptionInterface $e). Failing this class is the early warning that the public contract has drifted.

Documentation

• New "Exception handling" subsection in README.md covering the marker interface, the SPL parent table, the PSR-18 co-implementation, and the 4.x → 5.0 catch-block migration.
• Existing validateIdToken example in the README now catches the marker interface instead of the deprecated abstract.

Consumer migration

Mechanical, no semantic changes:

• catch (ItkOpenIdConnectException $e) → catch (OpenIdConnectExceptionInterface $e).
• Catches on concrete types (CacheException, ValidationException, ClaimsException, …) need no change — class names and namespaces are stable.
• Catches on \Exception continue to match.
• New: catches on \RuntimeException (e.g. generic retry decorators) now match transient OIDC failures, which is the intended semantic; previously such code was invisible to library exceptions. Flagged for upgrade-notes review.

Test plan

• task test:coverage — 87 tests, 135 assertions; 100% coverage on OpenIdConfigurationProvider (24/24 methods, 148/148 lines) preserved; new ExceptionHierarchyTest class adds 43 assertions across 15 data sets.
• task analyze:php — PHPStan max, no errors.
• task lint:php — clean.
• task lint:markdown — clean.
• CI matrix on PR (PHP 8.3/8.4/8.5 × stable/lowest).

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (984966b) to head (fcbb5b3).

Additional details and impacted files

@@             Coverage Diff             @@
##             develop       #40   +/-   ##
===========================================
  Coverage     100.00%   100.00%           
  Complexity        62        62           
===========================================
  Files              1         1           
  Lines            172       172           
===========================================
  Hits             172       172           

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jekuaitk]

If its unreachable lets just remove it.

Suggested change

	// @phpstan-ignore deadCode.unreachable
	$this->fail('Catch on OpenIdConnectExceptionInterface should have matched '.$concrete);

[turegjorup]

It is unreachable in current code, and as such is flagged by phpstan unless ignored. The purpose of the test is to flag future regressions if somebody updates the code and breaks the exception design contract. To do that we need to catch by interface (the contract) and fail if something falls through the catch. As long as the code follows the contract, the "fail" will be dead code