Maatify Verification Module

Overview

The Maatify\Verification module is a framework-agnostic verification code component designed for managing One-Time Passwords (OTPs) and temporary codes. It handles the complete lifecycle of verification codes, including generation, secure storage (hashing), validation, attempt tracking, expiration, and IP address auditing.

Installation

Install the package via Composer:

composer require maatify/verification

Architecture Summary

This module follows Domain-Driven Design (DDD) principles with strict separation between the domain logic and infrastructure concerns:

• Domain Layer: Contains core contracts (VerificationCodeGeneratorInterface, VerificationCodeValidatorInterface), DTOs (VerificationCode, GeneratedVerificationCode), and Services (VerificationCodeGenerator, VerificationCodeValidator) implementing the business rules for verification codes.
• Infrastructure Layer: Implements data persistence. By default, it includes PdoVerificationCodeRepository for database storage.
• Bootstrap Layer: Provides dependency injection container bindings (VerificationBindings) to ease integration.

Module Structure

src/
├── Bootstrap/                 # DI Container bindings
│   └── VerificationBindings.php
├── Domain/
│   ├── Contracts/             # Core interfaces
│   ├── DTO/                   # Data Transfer Objects
│   ├── Enum/                  # Strongly-typed Enums for state and types
│   └── Service/               # Business logic for generation and validation
├── Infrastructure/
│   └── Repository/            # Persistence implementations (e.g., PDO)
├── docs/                      # Extensive documentation
└── composer.json              # Standalone package definition

Quick Usage

To quickly get started with the module, register the bindings in your DI container and use the provided services:

use Maatify\Verification\Bootstrap\VerificationBindings;
use Maatify\Verification\Domain\Contracts\VerificationCodeGeneratorInterface;
use Maatify\Verification\Domain\Contracts\VerificationCodeValidatorInterface;
use Maatify\Verification\Domain\Enum\IdentityTypeEnum;
use Maatify\Verification\Domain\Enum\VerificationPurposeEnum;

// 1. Register bindings
VerificationBindings::register($containerBuilder);

// 2. Generate a verification code
/** @var VerificationCodeGeneratorInterface $generator */
$generator = $container->get(VerificationCodeGeneratorInterface::class);

$generated = $generator->generate(
    IdentityTypeEnum::Email,
    'user@example.com',
    VerificationPurposeEnum::EmailVerification,
    '192.168.1.100' // Optional IP tracking
);

// Send $generated->plainCode to the user...

// 3. Validate a verification code
/** @var VerificationCodeValidatorInterface $validator */
$validator = $container->get(VerificationCodeValidatorInterface::class);

$result = $validator->validate(
    IdentityTypeEnum::Email,
    'user@example.com',
    VerificationPurposeEnum::EmailVerification,
    '123456', // The plain code provided by the user
    '192.168.1.101' // Optional IP tracking for usage
);

if ($result->success) {
    // Verification successful
} else {
    // Verification failed: $result->reason
}

Further Documentation

• How to Use - Practical integration patterns.
• Changelog - History and evolution of the module.

Documentation Book

Comprehensive architecture and integration guides are available in the Book:

Chapter	Description
Table of Contents	Main entry point for the documentation book.
01. Overview	High-level module concepts and goals.
02. Architecture	Detailed layer boundaries and responsibilities.
03. Domain Model	Entities, DTOs, and Enums representing the verification state.
04. Verification Lifecycle	The strict lifecycle rules from creation to expiration.
05. Code Generation	How codes are generated, hashed, and policies applied.
06. Code Validation	The validation process, attempt tracking, and anti-brute-force.
07. Repository Layer	Data persistence strategies and infrastructure.
08. Container Bindings	Connecting the module to Dependency Injection containers.
09. Extension Points	Extending policies, storage, and identifier types.
10. Integration Patterns	Real-world usage inside larger applications.
11. Common Pitfalls	Mistakes to avoid when implementing the module.

License

This project is licensed under the MIT License. See the LICENSE file for details.