Add tasks for automation with Castor and made relevant updates (#557)

Introduced Castor tasks to automate and streamline the build process. Tasks include mutation testing, unit tests, static analysis, and coding standard checks. Various integration scripts were updated to use these tasks. Updated `.gitignore` and `.gitattributes` to handle Castor related files correctly. Documentation added or updated throughout the codebase for better code understanding.

Checker/AlgorithmChecker.php

@@ -9,8 +9,9 @@
 use function is_string;
 
 /**
- * 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.
+ * AlgorithmChecker class.
+ *
+ * This class implements the HeaderChecker interface and is responsible for checking the "alg" header in a token.
  */
 final readonly class AlgorithmChecker implements HeaderChecker
 {

Checker/AudienceChecker.php

@@ -10,8 +10,7 @@
 use function is_string;
 
 /**
- * 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.
+ * Represents a class that checks the audience claim and header in a JWT token.
  */
 final readonly class AudienceChecker implements ClaimChecker, HeaderChecker
 {

Checker/CallableChecker.php

@@ -10,6 +10,7 @@
 use function is_callable;
 
 /**
+ * This class is responsible for checking claims and headers using a callable function.
  * @see \Jose\Tests\Component\Checker\CallableCheckerTest
  */
 final class CallableChecker implements ClaimChecker, HeaderChecker

Checker/ClaimChecker.php

@@ -4,16 +4,19 @@
 
 namespace Jose\Component\Checker;
 
+/**
+ * Represents a claim checker interface.
+ * Claim checkers are responsible for validating claims on a token.
+ */
 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.
+     * Checks if the given value matches the claim.
      */
     public function checkClaim(mixed $value): void;
 
     /**
-     * The method returns the claim to be checked.
+     * Returns the supported claim.
      */
     public function supportedClaim(): string;
 }

Checker/ClaimCheckerManager.php

@@ -8,8 +8,7 @@
 use function count;
 
 /**
- * This manager handles as many claim checkers as needed.
- *
+ * This class manages claim checkers and performs claim checks.
  * @see \Jose\Tests\Component\Checker\ClaimCheckerManagerTest
  */
 class ClaimCheckerManager

Checker/ClaimCheckerManagerFactory.php

@@ -7,6 +7,7 @@
 use InvalidArgumentException;
 
 /**
+ * This class is responsible for creating and managing claim checkers.
  * @see \Jose\Tests\Component\Checker\ClaimCheckerManagerFactoryTest
  */
 class ClaimCheckerManagerFactory

Checker/ClaimExceptionInterface.php

@@ -7,7 +7,10 @@
 use Throwable;
 
 /**
- * Exceptions thrown by this component.
+ * Represents an interface for claim exceptions.
+ *
+ * This interface extends from the Throwable interface, allowing
+ * the claim exceptions to be thrown and caught like any other exception.
  */
 interface ClaimExceptionInterface extends Throwable
 {

Checker/ExpirationTimeChecker.php

@@ -10,7 +10,9 @@
 use function is_int;
 
 /**
- * This class is a claim checker. When the "exp" is present, it will compare the value with the current timestamp.
+ * This class is a claim checker.
+ *
+ * When the "exp" is present, it will compare the value with the current timestamp.
  */
 final readonly class ExpirationTimeChecker implements ClaimChecker, HeaderChecker
 {

Checker/HeaderChecker.php

@@ -4,21 +4,25 @@
 
 namespace Jose\Component\Checker;
 
+/**
+ * Interface HeaderChecker
+ *
+ * This interface defines the contract for a header checker.
+ */
 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.
+     * Checks if the given value matches the header parameter of the token.
      */
     public function checkHeader(mixed $value): void;
 
     /**
-     * The method returns the header parameter to be checked.
+     * Retrieves the supported header for the token.
      */
     public function supportedHeader(): string;
 
     /**
-     * When true, the header parameter to be checked MUST be set in the protected header of the token.
+     * Returns a boolean value indicating whether the requested resource can only be accessed with a protected header.
      */
     public function protectedHeaderOnly(): bool;
 }

Checker/HeaderCheckerManager.php

@@ -10,6 +10,12 @@
 use function count;
 use function is_array;
 
+/**
+ * This class is a factory to create Header Checker Managers.
+ *
+ * It allows to add header parameter checkers and token type supports.
+ * The factory is responsible to create a Header Checker Manager with the header parameter checkers found based
+ */
 class HeaderCheckerManager
 {
     /**

Checker/HeaderCheckerManagerFactory.php

@@ -7,6 +7,9 @@
 use InvalidArgumentException;
 
 /**
+ * This class is a factory to create Header Checker Managers. It allows to add header parameter checkers and token type
+ * supports. The factory is responsible to create a Header Checker Manager with the header parameter checkers found based
+ * on the alias. If the alias is not supported, an InvalidArgumentException is thrown.
  * @see \Jose\Tests\Component\Checker\HeaderCheckerManagerFactoryTest
  */
 class HeaderCheckerManagerFactory

Checker/InvalidHeaderException.php

@@ -7,7 +7,7 @@
 use Exception;
 
 /**
- * This exception is thrown by header parameter checkers when a header parameter check failed.
+ * This exception is thrown by header checkers when a header check failed.
  */
 class InvalidHeaderException extends Exception
 {

Checker/IsEqualChecker.php

@@ -7,6 +7,7 @@
 use Override;
 
 /**
+ * This class implements a claim and header checker that checks if the value is equal to the expected value.
  * @see \Jose\Tests\Component\Checker\IsEqualCheckerTest
  */
 final readonly class IsEqualChecker implements ClaimChecker, HeaderChecker

Checker/IssuerChecker.php

@@ -9,8 +9,9 @@
 use function is_string;
 
 /**
- * This class is a header parameter and claim checker. When the "iss" header parameter or claim is present, it will
- * check if the value is within the allowed ones.
+ * This class is a header parameter and claim checker.
+ *
+ * When the "iss" header parameter or claim is present, it will check if the value is within the allowed ones.
  */
 final readonly class IssuerChecker implements ClaimChecker, HeaderChecker
 {

Checker/MissingMandatoryClaimException.php

@@ -6,6 +6,9 @@
 
 use Exception;
 
+/**
+ * This exception is thrown by claim checkers when a mandatory claim is missing.
+ */
 class MissingMandatoryClaimException extends Exception implements ClaimExceptionInterface
 {
     /**

Checker/TokenTypeSupport.php

@@ -6,6 +6,13 @@
 
 use Jose\Component\Core\JWT;
 
+/**
+ * This interface is used to support token types.
+ *
+ * The token type is a way to define the format of the token.
+ * For example, the JWE token type is used to define the format of the token when it is encrypted.
+ * The JWS token type is used to define the format of the token when it is signed.
+ */
 interface TokenTypeSupport
 {
     /**