Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Spomky merged 1 commit into from
Aug 29, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 0 additions & 114 deletions .ci-tools/phpstan-baseline.neon
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3822,48 +3822,6 @@ parameters:
count: 1
path: ../src/Bundle/Services/ClaimCheckerManagerFactory.php

-
rawMessage: 'Method Jose\Component\Encryption\JWEDecrypterInterface::decryptUsingKeySet() invoked with 6 parameters, 3-5 required.'
identifier: arguments.count
count: 1
path: ../src/Bundle/Services/EventDispatchingJWEDecrypter.php

-
rawMessage: 'Parameter #3 $JWK of class Jose\Bundle\JoseFramework\Event\JWEDecryptionSuccessEvent constructor expects Jose\Component\Core\JWK, Jose\Component\Core\JWK|null given.'
identifier: argument.type
count: 1
path: ../src/Bundle/Services/EventDispatchingJWEDecrypter.php

-
rawMessage: 'Parameter #4 $recipient of class Jose\Bundle\JoseFramework\Event\JWELoadingSuccessEvent constructor expects int, int|null given.'
identifier: argument.type
count: 1
path: ../src/Bundle/Services/EventDispatchingJWELoader.php

-
rawMessage: 'Parameter #4 $signature of class Jose\Bundle\JoseFramework\Event\JWSLoadingSuccessEvent constructor expects int, int|null given.'
identifier: argument.type
count: 1
path: ../src/Bundle/Services/EventDispatchingJWSLoader.php

-
rawMessage: 'Method Jose\Component\Signature\JWSVerifierInterface::verifyWithKeySet() invoked with 6 parameters, 3-5 required.'
identifier: arguments.count
count: 1
path: ../src/Bundle/Services/EventDispatchingJWSVerifier.php

-
rawMessage: 'Parameter #5 $JWK of class Jose\Bundle\JoseFramework\Event\JWSVerificationSuccessEvent constructor expects Jose\Component\Core\JWK, Jose\Component\Core\JWK|null given.'
identifier: argument.type
count: 1
path: ../src/Bundle/Services/EventDispatchingJWSVerifier.php

-
rawMessage: 'Parameter #5 $signature of class Jose\Bundle\JoseFramework\Event\NestedTokenLoadingSuccessEvent constructor expects int, int|null given.'
identifier: argument.type
count: 1
path: ../src/Bundle/Services/EventDispatchingNestedTokenLoader.php

-
rawMessage: Class Jose\Bundle\JoseFramework\Services\HeaderCheckerManager extends @final class Jose\Component\Checker\HeaderCheckerManager.
identifier: class.extendsFinalByPhpDoc
Expand Down Expand Up @@ -3942,12 +3900,6 @@ parameters:
count: 1
path: ../src/Bundle/Services/JWEDecrypter.php

-
rawMessage: 'Parameter #3 $JWK of class Jose\Bundle\JoseFramework\Event\JWEDecryptionSuccessEvent constructor expects Jose\Component\Core\JWK, Jose\Component\Core\JWK|null given.'
identifier: argument.type
count: 1
path: ../src/Bundle/Services/JWEDecrypter.php

-
rawMessage: '''
Call to method __construct() of deprecated class Jose\Bundle\JoseFramework\Services\JWEDecrypter:
Expand Down Expand Up @@ -3996,12 +3948,6 @@ parameters:
count: 1
path: ../src/Bundle/Services/JWELoader.php

-
rawMessage: 'Parameter #4 $recipient of class Jose\Bundle\JoseFramework\Event\JWELoadingSuccessEvent constructor expects int, int|null given.'
identifier: argument.type
count: 1
path: ../src/Bundle/Services/JWELoader.php

-
rawMessage: '''
Call to method __construct() of deprecated class Jose\Bundle\JoseFramework\Services\JWELoader:
Expand Down Expand Up @@ -4074,12 +4020,6 @@ parameters:
count: 1
path: ../src/Bundle/Services/JWSLoader.php

-
rawMessage: 'Parameter #4 $signature of class Jose\Bundle\JoseFramework\Event\JWSLoadingSuccessEvent constructor expects int, int|null given.'
identifier: argument.type
count: 1
path: ../src/Bundle/Services/JWSLoader.php

-
rawMessage: '''
Call to method __construct() of deprecated class Jose\Bundle\JoseFramework\Services\JWSLoader:
Expand Down Expand Up @@ -4146,12 +4086,6 @@ parameters:
count: 1
path: ../src/Bundle/Services/JWSVerifier.php

-
rawMessage: 'Parameter #5 $JWK of class Jose\Bundle\JoseFramework\Event\JWSVerificationSuccessEvent constructor expects Jose\Component\Core\JWK, Jose\Component\Core\JWK|null given.'
identifier: argument.type
count: 1
path: ../src/Bundle/Services/JWSVerifier.php

-
rawMessage: '''
Call to method __construct() of deprecated class Jose\Bundle\JoseFramework\Services\JWSVerifier:
Expand Down Expand Up @@ -4284,12 +4218,6 @@ parameters:
count: 1
path: ../src/Bundle/Services/NestedTokenLoader.php

-
rawMessage: 'Parameter #5 $signature of class Jose\Bundle\JoseFramework\Event\NestedTokenLoadingSuccessEvent constructor expects int, int|null given.'
identifier: argument.type
count: 1
path: ../src/Bundle/Services/NestedTokenLoader.php

-
rawMessage: '''
Call to method __construct() of deprecated class Jose\Bundle\JoseFramework\Services\NestedTokenLoader:
Expand Down Expand Up @@ -4909,18 +4837,6 @@ parameters:
count: 1
path: ../src/Library/Encryption/JWEDecrypter.php

-
rawMessage: 'Parameter #1 $key of static method Jose\Component\Core\Util\KeyChecker::checkKeyAlgorithm() expects Jose\Component\Core\JWK, mixed given.'
identifier: argument.type
count: 2
path: ../src/Library/Encryption/JWEDecrypter.php

-
rawMessage: 'Parameter #1 $key of static method Jose\Component\Core\Util\KeyChecker::checkKeyUsage() expects Jose\Component\Core\JWK, mixed given.'
identifier: argument.type
count: 1
path: ../src/Library/Encryption/JWEDecrypter.php

-
rawMessage: 'Parameter #3 $completeHeader of method Jose\Component\Encryption\Algorithm\KeyEncryption\KeyWrapping::unwrapKey() expects array<string, mixed>, array given.'
identifier: argument.type
Expand All @@ -4933,12 +4849,6 @@ parameters:
count: 1
path: ../src/Library/Encryption/JWEDecrypter.php

-
rawMessage: 'Parameter #3 $recipientKey of method Jose\Component\Encryption\JWEDecrypter::decryptCEK() expects Jose\Component\Core\JWK, mixed given.'
identifier: argument.type
count: 1
path: ../src/Library/Encryption/JWEDecrypter.php

-
rawMessage: 'Parameter #5 $completeHeader of method Jose\Component\Encryption\Algorithm\KeyEncryption\KeyAgreement::getAgreementKey() expects array<string, mixed>, array given.'
identifier: argument.type
Expand All @@ -4951,18 +4861,6 @@ parameters:
count: 1
path: ../src/Library/Encryption/JWEDecrypter.php

-
rawMessage: 'Parameter &$successJwk by-ref type of method Jose\Component\Encryption\JWEDecrypter::decryptRecipientKey() expects Jose\Component\Core\JWK|null, mixed given.'
identifier: parameterByRef.type
count: 1
path: ../src/Library/Encryption/JWEDecrypter.php

-
rawMessage: 'Method Jose\Component\Encryption\JWEDecrypterInterface::decryptUsingKeySet() invoked with 6 parameters, 3-5 required.'
identifier: arguments.count
count: 1
path: ../src/Library/Encryption/JWELoader.php

-
rawMessage: 'Method Jose\Component\Encryption\JWELoaderFactory::create() has parameter $encryptionAlgorithms with no value type specified in iterable type array.'
identifier: missingType.iterableValue
Expand Down Expand Up @@ -5365,12 +5263,6 @@ parameters:
count: 1
path: ../src/Library/KeyManagement/KeyConverter/RSAKey.php

-
rawMessage: 'Parameter #2 $recipient of method Jose\Component\NestedToken\NestedTokenLoader::checkContentTypeHeader() expects int, int|null given.'
identifier: argument.type
count: 1
path: ../src/Library/NestedToken/NestedTokenLoader.php

-
rawMessage: 'Parameter #1 $signature of static method Jose\Component\Core\Util\ECSignature::fromAsn1() expects string, mixed given.'
identifier: argument.type
Expand Down Expand Up @@ -5401,12 +5293,6 @@ parameters:
count: 1
path: ../src/Library/Signature/Algorithm/Util/RSA.php

-
rawMessage: 'Method Jose\Component\Signature\JWSVerifierInterface::verifyWithKeySet() invoked with 6 parameters, 3-5 required.'
identifier: arguments.count
count: 1
path: ../src/Library/Signature/JWSLoader.php

-
rawMessage: 'Parameter #1 $algorithm of method Jose\Component\Core\AlgorithmManager::get() expects string, mixed given.'
identifier: argument.type
Expand Down
88 changes: 70 additions & 18 deletions src/Bundle/Services/EventDispatchingJWEDecrypter.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,16 @@
use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Core\JWK;
use Jose\Component\Core\JWKSet;
use Jose\Component\Encryption\DecryptionResult;
use Jose\Component\Encryption\JWE;
use Jose\Component\Encryption\JWEDecrypterInterface;
use Override;
use Psr\EventDispatcher\EventDispatcherInterface;
use Throwable;
use function func_get_arg;
use function func_num_args;
use function is_callable;
use function trigger_deprecation;

/**
* Dispatches an event whenever a recipient is decrypted, without extending the decrypter it decorates.
Expand All @@ -39,43 +43,91 @@ public function getContentEncryptionAlgorithmManager(): AlgorithmManager
return $this->decrypter->getContentEncryptionAlgorithmManager();
}

/**
* A JWE that already has a payload is reported as decrypted without any key being used. There is nothing to
* report in that case, hence no event at all.
*
* @param (callable(Throwable): void)|null $onError
*/
#[Override]
public function decrypt(
JWE $jwe,
JWK|JWKSet $keys,
int $recipientIndex,
?JWK $senderKey = null,
?callable $onError = null
): DecryptionResult {
$result = $this->decrypter->decrypt($jwe, $keys, $recipientIndex, $senderKey, $onError);
$jwkset = $keys instanceof JWK ? new JWKSet([$keys]) : $keys;
$jwk = $result->getKey();
if ($jwk !== null) {
$this->eventDispatcher->dispatch(
new JWEDecryptionSuccessEvent($result->getJwe(), $jwkset, $jwk, $recipientIndex)
);
} elseif (! $result->isDecrypted()) {
$this->eventDispatcher->dispatch(new JWEDecryptionFailureEvent($jwe, $jwkset));
}

return $result;
}

/**
* @deprecated since 4.3.0, use "decrypt()" instead. Will be removed in 5.0.0.
*/
public function decryptUsingKey(JWE &$jwe, JWK $jwk, int $recipient, ?JWK $senderKey = null): bool
{
trigger_deprecation(
'web-token/jwt-framework',
'4.3.0',
'The method "%s::decryptUsingKey()" is deprecated and will be removed in 5.0.0. Please use "%s::decrypt()" instead: it returns a "%s" object that carries the decrypted JWE instead of replacing the variable of the caller.',
self::class,
self::class,
DecryptionResult::class
);
$jwkset = new JWKSet([$jwk]);
$successJwk = null;

return $this->decryptUsingKeySet($jwe, $jwkset, $recipient, $successJwk, $senderKey);
}

/**
* The callable used by the loaders to observe the keys that were discarded is not part of the signature yet: it is
* read with func_num_args()/func_get_arg(5) and forwarded to the decorated decrypter, otherwise the reason of a
* failure would be lost as soon as the decrypter is decorated.
* The callable used by the loaders to observe the keys that were discarded is not part of the signature: it is
* read with func_num_args()/func_get_arg(5) and forwarded to "decrypt()", otherwise the reason of a failure would
* be lost as soon as the decrypter is decorated.
*
* @param-out JWK|null $jwk
*
* @deprecated since 4.3.0, use "decrypt()" instead. Will be removed in 5.0.0.
*/
#[Override]
public function decryptUsingKeySet(
JWE &$jwe,
JWKSet $jwkset,
int $recipient,
?JWK &$jwk = null,
?JWK $senderKey = null
): bool {
$success = func_num_args() >= 6 ? $this->decrypter->decryptUsingKeySet(
$jwe,
$jwkset,
$recipient,
$jwk,
$senderKey,
func_get_arg(5)
) : $this->decrypter->decryptUsingKeySet($jwe, $jwkset, $recipient, $jwk, $senderKey);

if ($success) {
$this->eventDispatcher->dispatch(new JWEDecryptionSuccessEvent($jwe, $jwkset, $jwk, $recipient));
} else {
$this->eventDispatcher->dispatch(new JWEDecryptionFailureEvent($jwe, $jwkset));
trigger_deprecation(
'web-token/jwt-framework',
'4.3.0',
'The method "%s::decryptUsingKeySet()" is deprecated and will be removed in 5.0.0. Please use "%s::decrypt()" instead: it returns a "%s" object that carries the decrypted JWE and the key instead of replacing the variables of the caller.',
self::class,
self::class,
DecryptionResult::class
);
$onError = func_num_args() >= 6 ? func_get_arg(5) : null;
if (! is_callable($onError)) {
$onError = null;
}
$result = $this->decrypt($jwe, $jwkset, $recipient, $senderKey, $onError);
if (! $result->isDecrypted()) {
return false;
}
$jwe = $result->getJwe();
$successJwk = $result->getKey();
if ($successJwk !== null) {
$jwk = $successJwk;
}

return $success;
return true;
}
}
Loading
Loading