feat(core): return result objects instead of by-reference output parameters

[Spomky]

Closes #685. Rebased on 4.3.x after #709 (service interfaces) and #707 (exception hierarchy).

What changes

Readonly result objects replace the by-reference output parameters listed in the issue. The new methods sit next to the old ones, and the old ones are implemented on top of them, so nothing breaks.

Before	After
JWSVerifier::verifyWithKeySet($jws, $jwkset, 0, null, $jwk)	verify($jws, $keys, 0) → VerificationResult
JWEDecrypter::decryptUsingKey/KeySet($jwe, …)	decrypt($jwe, $keys, 0) → DecryptionResult
JWSLoader::loadAndVerifyWithKey/KeySet($token, …, $signature)	loadAndVerify($token, $keys) → LoadingResult
JWELoader::loadAndDecryptWithKey/KeySet($token, …, $recipient)	loadAndDecrypt($token, $keys) → LoadingResult
JWSSerializerManager::unserialize($input, $name)	unserializeToken($input) → UnserializationResult
JWESerializerManager::unserialize($input, $name)	unserializeToken($input) → UnserializationResult
NestedTokenLoader::load($token, …, $signature)	loadAndVerify($token, …) → LoadingResult

$result = $jwsVerifier->verify($jws, $jwkset, 0);
if ($result->isVerified()) {
    $key = $result->getKey();
}

$result = $jweDecrypter->decrypt($jwe, $jwkset, 0);
if ($result->isDecrypted()) {
    $jwe = $result->getJwe();   // the JWE given to the decrypter is left untouched
}

Two other things the new methods gain:

• they accept a JWK as well as a JWKSet, so the …WithKey() / …WithKeySet() pairs collapse into one method;
• the callable that observes the keys discarded along the way — added in fix(encryption): read the recipient header from the builder state #698 behind func_get_arg() because a signature cannot change in a minor — is a declared argument of verify() and decrypt().

The $signature / $signatureIndex docblock mismatch of verifyWithKeySet() is fixed on the docblock side: renaming the parameter would break callers already using named arguments.

No return type changes

No existing method changed its signature. verifyWithKeySet() still returns bool, loadAndVerifyWithKeySet() still returns JWS, unserialize() still returns JWS/JWE, load() still returns JWS. The result objects are only returned by the new methods.

The new methods are declared on the interfaces of #709

JWSVerifierInterface, JWEDecrypterInterface, JWSLoaderInterface, JWELoaderInterface and NestedTokenLoaderInterface gain the new method, and the deprecated ones are tagged @deprecated there too. Adding a method to a published interface is a hard BC break, so this is only free because those interfaces have not shipped yet — worth a conscious ack before merging.

It is also what makes the design hold together: JWSLoader receives a JWSVerifierInterface, so without the declaration it could not call verify() and would have to keep calling the deprecated method internally. It also keeps decoration — the extension mechanism #709 established — working for the new API.

Deprecations

verifyWithKeySet(), decryptUsingKey(), decryptUsingKeySet(), loadAndVerifyWithKey(), loadAndVerifyWithKeySet(), loadAndDecryptWithKey() and loadAndDecryptWithKeySet() trigger a deprecation and will be removed in 5.0.0. Their output parameter is required, so the methods cannot survive without it.

JWSSerializerManager::unserialize(), JWESerializerManager::unserialize() and NestedTokenLoader::load() keep working as they are: their output parameter is optional, so only passing it is deprecated, and only the argument goes away in 5.0.0. Calling unserialize($input) or load($token, $encryptionKeySet, $signatureKeySet) triggers nothing.

Algorithm interfaces

As in #654, changing encryptContent(), encryptKey(), wrapKey() and getAgreementKey() cannot be done additively without breaking every third-party implementation. 4.3.0 only documents the signature they will have in 5.0.0 and ships the objects they will return: EncryptedContent (ciphertext + tag) and WrappedKey (key + additional header parameters).

Bundle

Both families of services implement the new methods:

• the EventDispatching* decorators dispatch from the new method and implement the deprecated ones on top of it, so an event is dispatched exactly once whichever API the application uses;
• the deprecated inheritance-based services do the same, so they stay behaviourally identical to what they were.

Two decisions worth a look

• decrypt() does not throw on failure. The issue's example has it throwing, but decryptUsingKeySet() already throws for an empty key set or a JWE without recipients, and those must keep propagating. A dedicated exception would be needed to tell "no key worked" apart from them; isDecrypted() keeps the old semantics, mirrors isVerified() and makes the deprecated method a two-line wrapper.
• NestedTokenLoader is included although it is not in the issue's table — its load() has the same ?int &$signature idiom.

Checks

• phpunit: 1033 tests green, including 23 new ones covering the result objects, the deprecations and the unchanged behaviour of the deprecated methods.
• ecs, rector --dry-run: clean on the touched files.
• phpstan: no new error, and the set of unmatched baseline entries is identical to the one on a pristine 4.3.x. Nineteen baseline entries are dropped — the by-ref, int|null and arguments.count types they described are gone, JWEDecrypter now iterates JWKSet::all() instead of the @internal iterator, and the deprecated loader methods declare @param-out int.