feat: introduce VerificationService orchestration layer

composer.json

@@ -6,10 +6,10 @@
 
   "require": {
     "php": "^8.2",
-    "ext-pdo": "*",
     "ext-json": "*",
+    "ext-pdo": "*",
     "ext-redis": "*",
-
+    "maatify/exceptions": "^1.1",
     "maatify/shared-common": "^1.0"
   },
 

src/Application/Exceptions/VerificationAttemptsExceededException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Verification\Application\Exceptions;
+
+use Maatify\Exceptions\Contracts\ErrorCategoryInterface;
+use Maatify\Exceptions\Enum\ErrorCategoryEnum;
+
+class VerificationAttemptsExceededException extends VerificationException
+{
+    protected string $errorCode = 'VERIFICATION_ATTEMPTS_EXCEEDED';
+    protected string $messageKey = 'verification.attempts_exceeded';
+    protected int $statusCode = 429;
+    protected ErrorCategoryInterface $category = ErrorCategoryEnum::RATE_LIMIT;
+}

src/Application/Exceptions/VerificationErrorCodeEnum.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Verification\Application\Exceptions;
+
+use Maatify\Exceptions\Contracts\ErrorCodeInterface;
+
+enum VerificationErrorCodeEnum: string implements ErrorCodeInterface
+{
+    case VERIFICATION_INVALID_CODE = 'VERIFICATION_INVALID_CODE';
+    case VERIFICATION_EXPIRED = 'VERIFICATION_EXPIRED';
+    case VERIFICATION_ATTEMPTS_EXCEEDED = 'VERIFICATION_ATTEMPTS_EXCEEDED';
+    case VERIFICATION_GENERATION_BLOCKED = 'VERIFICATION_GENERATION_BLOCKED';
+    case VERIFICATION_INTERNAL = 'VERIFICATION_INTERNAL';
+
+    public function getValue(): string
+    {
+        return $this->value;
+    }
+}

src/Application/Exceptions/VerificationException.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Verification\Application\Exceptions;
+
+use Maatify\Exceptions\Contracts\ErrorCategoryInterface;
+use Maatify\Exceptions\Contracts\ErrorCodeInterface;
+use Maatify\Exceptions\Contracts\ErrorPolicyInterface;
+use Maatify\Exceptions\Contracts\EscalationPolicyInterface;
+use Maatify\Exceptions\Enum\ErrorCategoryEnum;
+use Maatify\Exceptions\Exception\MaatifyException;
+use Throwable;
+
+abstract class VerificationException extends MaatifyException
+{
+    protected string $errorCode = 'VERIFICATION_INTERNAL';
+    protected string $messageKey = 'verification.internal_error';
+    protected int $statusCode = 500;
+    protected ErrorCategoryInterface $category = ErrorCategoryEnum::SYSTEM;
+
+    public function __construct(
+        string $message = '',
+        int $code = 0,
+        ?Throwable $previous = null,
+        ?ErrorCodeInterface $errorCodeOverride = null,
+        ?int $httpStatusOverride = null,
+        ?bool $isSafeOverride = null,
+        ?bool $isRetryableOverride = null,
+        array $meta = [],
+        ?ErrorPolicyInterface $policy = null,
+        ?EscalationPolicyInterface $escalationPolicy = null
+    ) {
+        if ($message === '') {
+            $message = $this->messageKey;
+        }
+
+        parent::__construct(
+            $message,
+            $code,
+            $previous,
+            $errorCodeOverride,
+            $httpStatusOverride,
+            $isSafeOverride,
+            $isRetryableOverride,
+            $meta,
+            $policy,
+            $escalationPolicy
+        );
+    }
+
+    protected function defaultErrorCode(): ErrorCodeInterface
+    {
+        return VerificationErrorCodeEnum::from($this->errorCode);
+    }
+
+    protected function defaultCategory(): ErrorCategoryInterface
+    {
+        return $this->category;
+    }
+
+    protected function defaultHttpStatus(): int
+    {
+        return $this->statusCode;
+    }
+}

src/Application/Exceptions/VerificationExpiredException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Verification\Application\Exceptions;
+
+use Maatify\Exceptions\Contracts\ErrorCategoryInterface;
+use Maatify\Exceptions\Enum\ErrorCategoryEnum;
+
+class VerificationExpiredException extends VerificationException
+{
+    protected string $errorCode = 'VERIFICATION_EXPIRED';
+    protected string $messageKey = 'verification.expired';
+    protected int $statusCode = 410;
+    protected ErrorCategoryInterface $category = ErrorCategoryEnum::BUSINESS_RULE;
+}

src/Application/Exceptions/VerificationGenerationBlockedException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Verification\Application\Exceptions;
+
+use Maatify\Exceptions\Contracts\ErrorCategoryInterface;
+use Maatify\Exceptions\Enum\ErrorCategoryEnum;
+
+class VerificationGenerationBlockedException extends VerificationException
+{
+    protected string $errorCode = 'VERIFICATION_GENERATION_BLOCKED';
+    protected string $messageKey = 'verification.generation_blocked';
+    protected int $statusCode = 429;
+    protected ErrorCategoryInterface $category = ErrorCategoryEnum::RATE_LIMIT;
+}

src/Application/Exceptions/VerificationInternalException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Verification\Application\Exceptions;
+
+use Maatify\Exceptions\Contracts\ErrorCategoryInterface;
+use Maatify\Exceptions\Enum\ErrorCategoryEnum;
+
+class VerificationInternalException extends VerificationException
+{
+    protected string $errorCode = 'VERIFICATION_INTERNAL';
+    protected string $messageKey = 'verification.internal_error';
+    protected int $statusCode = 500;
+    protected ErrorCategoryInterface $category = ErrorCategoryEnum::SYSTEM;
+}

src/Application/Exceptions/VerificationInvalidCodeException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Verification\Application\Exceptions;
+
+use Maatify\Exceptions\Contracts\ErrorCategoryInterface;
+use Maatify\Exceptions\Enum\ErrorCategoryEnum;
+
+class VerificationInvalidCodeException extends VerificationException
+{
+    protected string $errorCode = 'VERIFICATION_INVALID_CODE';
+    protected string $messageKey = 'verification.invalid_code';
+    protected int $statusCode = 422;
+    protected ErrorCategoryInterface $category = ErrorCategoryEnum::VALIDATION;
+}

src/Application/Verification/VerificationService.php

@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Verification\Application\Verification;
+
+use Maatify\Verification\Application\Exceptions\VerificationAttemptsExceededException;
+use Maatify\Verification\Application\Exceptions\VerificationExpiredException;
+use Maatify\Verification\Application\Exceptions\VerificationGenerationBlockedException;
+use Maatify\Verification\Application\Exceptions\VerificationInternalException;
+use Maatify\Verification\Application\Exceptions\VerificationInvalidCodeException;
+use Maatify\Verification\Domain\Contracts\VerificationCodeGeneratorInterface;
+use Maatify\Verification\Domain\Contracts\VerificationCodeValidatorInterface;
+use Maatify\Verification\Domain\Enum\IdentityTypeEnum;
+use Maatify\Verification\Domain\Enum\VerificationFailureEnum;
+use Maatify\Verification\Domain\Enum\VerificationPurposeEnum;
+use Maatify\Verification\Domain\Exception\VerificationGenerationRateLimitedException;
+use Throwable;
+
+readonly class VerificationService implements VerificationServiceInterface
+{
+    public function __construct(
+        private VerificationCodeGeneratorInterface $generator,
+        private VerificationCodeValidatorInterface $validator
+    ) {
+    }
+
+    public function startVerification(
+        IdentityTypeEnum $identityType,
+        string $identity,
+        VerificationPurposeEnum $purpose
+    ): string {
+        try {
+            $generated = $this->generator->generate($identityType, $identity, $purpose);
+
+            return $generated->plainCode;
+        } catch (VerificationGenerationRateLimitedException $e) {
+            throw new VerificationGenerationBlockedException($e->getMessage(), 0, $e);
+        } catch (Throwable $e) {
+            throw new VerificationInternalException('An unexpected verification error occurred.', 0, $e);
+        }
+    }
+
+    public function verifyCode(
+        IdentityTypeEnum $identityType,
+        string $identity,
+        VerificationPurposeEnum $purpose,
+        string $code
+    ): bool {
+        try {
+            $result = $this->validator->validate($identityType, $identity, $purpose, $code);
+
+            if (! $result->success) {
+                return match ($result->failureCode) {
+                    VerificationFailureEnum::INVALID_CODE => throw new VerificationInvalidCodeException($result->reason),
+                    VerificationFailureEnum::EXPIRED => throw new VerificationExpiredException($result->reason),
+                    VerificationFailureEnum::ATTEMPTS_EXCEEDED => throw new VerificationAttemptsExceededException($result->reason),
+                    default => throw new VerificationInternalException($result->reason),
+                };
+            }
+
+            return true;
+        } catch (VerificationInvalidCodeException | VerificationExpiredException | VerificationAttemptsExceededException $e) {
+            throw $e;
+        } catch (Throwable $e) {
+            throw new VerificationInternalException('An unexpected verification error occurred.', 0, $e);
+        }
+    }
+
+    public function resendVerification(
+        IdentityTypeEnum $identityType,
+        string $identity,
+        VerificationPurposeEnum $purpose
+    ): string {
+        try {
+            $generated = $this->generator->generate($identityType, $identity, $purpose);
+
+            return $generated->plainCode;
+        } catch (VerificationGenerationRateLimitedException $e) {
+            throw new VerificationGenerationBlockedException($e->getMessage(), 0, $e);
+        } catch (Throwable $e) {
+            throw new VerificationInternalException('An unexpected verification error occurred.', 0, $e);
+        }
+    }
+}

src/Application/Verification/VerificationServiceInterface.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Verification\Application\Verification;
+
+use Maatify\Verification\Domain\Enum\IdentityTypeEnum;
+use Maatify\Verification\Domain\Enum\VerificationPurposeEnum;
+
+interface VerificationServiceInterface
+{
+    /**
+     * Starts a new verification process by generating a code.
+     *
+     * @param IdentityTypeEnum $identityType
+     * @param string $identity
+     * @param VerificationPurposeEnum $purpose
+     * @return string The plain generated verification code.
+     */
+    public function startVerification(
+        IdentityTypeEnum $identityType,
+        string $identity,
+        VerificationPurposeEnum $purpose
+    ): string;
+
+    /**
+     * Verifies an existing code.
+     *
+     * @param IdentityTypeEnum $identityType
+     * @param string $identity
+     * @param VerificationPurposeEnum $purpose
+     * @param string $code
+     * @return bool True if verification succeeds, false otherwise.
+     */
+    public function verifyCode(
+        IdentityTypeEnum $identityType,
+        string $identity,
+        VerificationPurposeEnum $purpose,
+        string $code
+    ): bool;
+
+    /**
+     * Resends a verification code.
+     *
+     * @param IdentityTypeEnum $identityType
+     * @param string $identity
+     * @param VerificationPurposeEnum $purpose
+     * @return string The plain generated verification code.
+     */
+    public function resendVerification(
+        IdentityTypeEnum $identityType,
+        string $identity,
+        VerificationPurposeEnum $purpose
+    ): string;
+}

src/Domain/DTO/VerificationResult.php

@@ -5,6 +5,7 @@
 namespace Maatify\Verification\Domain\DTO;
 
 use Maatify\Verification\Domain\Enum\IdentityTypeEnum;
+use Maatify\Verification\Domain\Enum\VerificationFailureEnum;
 use Maatify\Verification\Domain\Enum\VerificationPurposeEnum;
 
 readonly class VerificationResult
@@ -14,17 +15,18 @@ public function __construct(
         public string $reason = '',
         public ?IdentityTypeEnum $identityType = null,
         public ?string $identityId = null,
-        public ?VerificationPurposeEnum $purpose = null
+        public ?VerificationPurposeEnum $purpose = null,
+        public ?VerificationFailureEnum $failureCode = null
     ) {
     }
 
     public static function success(?IdentityTypeEnum $identityType = null, ?string $identityId = null, ?VerificationPurposeEnum $purpose = null): self
     {
-        return new self(true, '', $identityType, $identityId, $purpose);
+        return new self(true, '', $identityType, $identityId, $purpose, null);
     }
 
-    public static function failure(string $reason): self
+    public static function failure(VerificationFailureEnum $failureCode, string $reason): self
     {
-        return new self(false, $reason);
+        return new self(false, $reason, null, null, null, $failureCode);
     }
 }

src/Domain/Enum/VerificationFailureEnum.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Verification\Domain\Enum;
+
+enum VerificationFailureEnum: string
+{
+    case INVALID_CODE = 'INVALID_CODE';
+    case EXPIRED = 'EXPIRED';
+    case ATTEMPTS_EXCEEDED = 'ATTEMPTS_EXCEEDED';
+}

src/Domain/Exception/VerificationGenerationRateLimitedException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Maatify\Verification\Domain\Exception;
+
+use RuntimeException;
+
+class VerificationGenerationRateLimitedException extends RuntimeException
+{
+}