Php doc (#95)

* PHPDoc updated for all public methods.

Author: Spomky

src/Bundle/JoseFramework/DataCollector/JWECollector.php

@@ -125,7 +125,7 @@ private function collectSupportedJWELoaders(array &$data)
         $data['jwe']['jwe_loaders'] = [];
         foreach ($this->jweLoaders as $id => $jweLoader) {
             $data['jwe']['jwe_loaders'][$id] = [
-                'serializers'                   => $jweLoader->getSerializerManager()->list(),
+                'serializers'                   => $jweLoader->getSerializerManager()->names(),
                 'key_encryption_algorithms'     => $jweLoader->getJweDecrypter()->getKeyEncryptionAlgorithmManager()->list(),
                 'content_encryption_algorithms' => $jweLoader->getJweDecrypter()->getContentEncryptionAlgorithmManager()->list(),
                 'compression_methods'           => $jweLoader->getJweDecrypter()->getCompressionMethodManager()->list(),

src/Bundle/JoseFramework/Tests/Functional/Encryption/JWELoaderTest.php

@@ -58,7 +58,7 @@ public function theWELoaderFactoryCanCreateAJWELoader()
         $jwe = $jweLoaderFactory->create(['jwe_compact'], ['RSA1_5'], ['A256GCM'], ['DEF']);
 
         self::assertInstanceOf(JWELoader::class, $jwe);
-        self::assertEquals(['jwe_compact'], $jwe->getSerializerManager()->list());
+        self::assertEquals(['jwe_compact'], $jwe->getSerializerManager()->names());
         self::assertEquals(['RSA1_5'], $jwe->getJweDecrypter()->getKeyEncryptionAlgorithmManager()->list());
         self::assertEquals(['A256GCM'], $jwe->getJweDecrypter()->getContentEncryptionAlgorithmManager()->list());
         self::assertEquals(['DEF'], $jwe->getJweDecrypter()->getCompressionMethodManager()->list());

src/Component/Checker/AlgorithmChecker.php

@@ -13,7 +13,11 @@
 
 namespace Jose\Component\Checker;
 
-class AlgorithmChecker implements HeaderChecker
+/**
+ * This class is a header parameter checker.
+ * When the "alg" header parameter is present, it will check if the value is within the allowed ones.
+ */
+final class AlgorithmChecker implements HeaderChecker
 {
     private const HEADER_NAME = 'alg';
 

src/Component/Checker/AudienceChecker.php

@@ -13,7 +13,11 @@
 
 namespace Jose\Component\Checker;
 
-class AudienceChecker implements ClaimChecker, HeaderChecker
+/**
+ * This class is a header parameter and claim checker.
+ * When the "aud" header parameter or claim is present, it will check if the value is within the allowed ones.
+ */
+final class AudienceChecker implements ClaimChecker, HeaderChecker
 {
     private const CLAIM_NAME = 'aud';
 

src/Component/Checker/ClaimChecker.php

@@ -16,13 +16,18 @@
 interface ClaimChecker
 {
     /**
+     * When the token has the applicable claim, the value is checked.
+     * If for some reason the value is not valid, an InvalidClaimException must be thrown.
+     *
      * @param mixed $value
      *
-     * @throws \InvalidArgumentException
+     * @throws InvalidClaimException
      */
     public function checkClaim($value);
 
     /**
+     * The method returns the claim to be checked.
+     *
      * @return string
      */
     public function supportedClaim(): string;

src/Component/Checker/ClaimCheckerManager.php

@@ -13,6 +13,9 @@
 
 namespace Jose\Component\Checker;
 
+/**
+ * This manager handles as many claim checkers as needed.
+ */
 class ClaimCheckerManager
 {
     /**
@@ -33,6 +36,9 @@ private function __construct(array $checkers)
     }
 
     /**
+     * This method creates the ClaimCheckerManager.
+     * The argument is a list of claim checkers objects.
+     *
      * @param ClaimChecker[] $checkers
      *
      * @return ClaimCheckerManager
@@ -56,6 +62,8 @@ private function add(ClaimChecker $checker): self
     }
 
     /**
+     * This method returns all checkers handled by this manager.
+     *
      * @return ClaimChecker[]
      */
     public function getCheckers(): array
@@ -64,8 +72,17 @@ public function getCheckers(): array
     }
 
     /**
+     * This method checks all the claims passed as argument.
+     * All claims are checked against the claim checkers.
+     * If one fails, the InvalidClaimException is thrown.
+     *
+     * This method returns an array with all checked claims.
+     * It is up to the implementor to decide use the claims that have not been checked.
+     *
      * @param array $claims
      *
+     * @throws InvalidClaimException
+     *
      * @return array
      */
     public function check(array $claims): array

src/Component/Checker/ClaimCheckerManagerFactory.php

@@ -21,6 +21,9 @@ class ClaimCheckerManagerFactory
     private $checkers = [];
 
     /**
+     * This method creates a Claim Checker Manager and populate it with the claim checkers found based on the alias.
+     * If the alias is not supported, an InvalidArgumentException is thrown.
+     *
      * @param string[] $aliases
      *
      * @return ClaimCheckerManager
@@ -40,6 +43,8 @@ public function create(array $aliases): ClaimCheckerManager
     }
 
     /**
+     * This method adds a claim checker to this factory.
+     *
      * @param string       $alias
      * @param ClaimChecker $checker
      *
@@ -53,6 +58,8 @@ public function add(string $alias, ClaimChecker $checker): self
     }
 
     /**
+     * Returns all claim checker aliases supported by this factory.
+     *
      * @return string[]
      */
     public function aliases(): array
@@ -61,6 +68,8 @@ public function aliases(): array
     }
 
     /**
+     * Returns all claim checkers supported by this factory.
+     *
      * @return ClaimChecker[]
      */
     public function all(): array

src/Component/Checker/ExpirationTimeChecker.php

@@ -13,7 +13,13 @@
 
 namespace Jose\Component\Checker;
 
-class ExpirationTimeChecker implements ClaimChecker
+/**
+ * This class is a claim checker.
+ * When the "exp" is present, it will compare the value with the current timestamp.
+ *
+ * A time drift is allowed but its use is NOT recommended.
+ */
+final class ExpirationTimeChecker implements ClaimChecker
 {
     private const CLAIM_NAME = 'exp';
 

src/Component/Checker/HeaderChecker.php

@@ -16,18 +16,25 @@
 interface HeaderChecker
 {
     /**
+     * This method is called when the header parameter is present.
+     * If for some reason the value is not valid, an InvalidHeaderException must be thrown.
+     *
      * @param mixed $value
      *
-     * @throws \InvalidArgumentException
+     * @throws InvalidHeaderException
      */
     public function checkHeader($value);
 
     /**
+     * The method returns the header parameter to be checked.
+     *
      * @return string
      */
     public function supportedHeader(): string;
 
     /**
+     * When true, the header parameter to be checked MUST be set in the protected header of the token.
+     *
      * @return bool
      */
     public function protectedHeaderOnly(): bool;

src/Component/Checker/HeaderCheckerManager.php

@@ -44,6 +44,11 @@ private function __construct(array $checkers, array $tokenTypes)
     }
 
     /**
+     * This method creates the HeaderCheckerManager.
+     * The first argument is a list of header parameter checkers objects.
+     * The second argument is a list of token type support objects.
+     * It is recommended to support only one token type per manager.
+     *
      * @param HeaderChecker[]    $checkers
      * @param TokenTypeSupport[] $tokenTypes
      *
@@ -55,6 +60,8 @@ public static function create(array $checkers, array $tokenTypes): self
     }
 
     /**
+     * This method returns all checkers handled by this manager.
+     *
      * @return HeaderChecker[]
      */
     public function getCheckers(): array
@@ -88,18 +95,22 @@ private function add(HeaderChecker $checker): self
     }
 
     /**
+     * This method checks all the header parameters passed as argument.
+     * All header parameters are checked against the header parameter checkers.
+     * If one fails, the InvalidHeaderException is thrown.
+     *
      * @param JWT $jwt
-     * @param int $component
+     * @param int $index
      *
      * @throws InvalidHeaderException
      */
-    public function check(JWT $jwt, int $component)
+    public function check(JWT $jwt, int $index)
     {
         foreach ($this->tokenTypes as $tokenType) {
             if ($tokenType->supports($jwt)) {
                 $protected = [];
                 $unprotected = [];
-                $tokenType->retrieveTokenHeaders($jwt, $component, $protected, $unprotected);
+                $tokenType->retrieveTokenHeaders($jwt, $index, $protected, $unprotected);
                 $this->checkDuplicatedHeaderParameters($protected, $unprotected);
                 $this->checkHeaders($protected, $unprotected);