Skip to content

README.full.md

Latest commit

 

History

History
265 lines (176 loc) · 5.72 KB

README.full.md

File metadata and controls

265 lines (176 loc) · 5.72 KB

🧩 Maatify Common — Full Documentation (v2.0.0)

Maatify Common Maatify Ecosystem

Core Foundation Helper Library for the Maatify Ecosystem

This document provides the full technical documentation for maatify/common v2.0.0, covering its finalized scope as a pure, framework-agnostic helper library.

⚠️ Starting from v2.0.0, maatify/common intentionally contains no infrastructure, no storage, and no contracts. All adapter, repository, Redis, and KV logic has been migrated to dedicated packages.

📑 Table of Contents

  1. Introduction
  2. Core Modules
  3. Design Scope & Architecture
  4. Directory Structure
  5. Testing & Coverage
  6. Migration Notes (1.x → 2.0.0)
  7. License

🧭 Introduction

maatify/common is the lowest-level shared dependency in the Maatify ecosystem.

It provides pure, reusable building blocks that are:

  • framework-agnostic
  • storage-agnostic
  • side-effect free
  • safe to reuse across all environments

The library focuses exclusively on helpers, DTOs, traits, enums, and validation utilities that can be consumed safely by any higher-level package.

🧩 Core Modules

✔ Pagination Module

Unified DTOs and helpers for paginated API responses and in-memory collections.

Includes:

  • PaginationDTO
  • PaginationResultDTO
  • PaginationHelper

✔ Security & Input Sanitization

Centralized input sanitization built on top of HTMLPurifier.

Includes:

  • InputSanitizer
  • SanitizesInputTrait

Ensures XSS-safe, normalized input handling.

✔ Traits & Core Patterns

Reusable patterns shared across the ecosystem.

Includes:

  • SingletonTrait
  • SanitizesInputTrait

Designed for safe reuse and predictable lifecycle behavior.

✔ Text Utilities

Low-level string manipulation helpers.

Includes:

  • TextFormatter
  • PlaceholderRenderer
  • RegexHelper
  • SecureCompare

✔ Date & Time Helpers

Localization-friendly date/time helpers.

Includes:

  • DateFormatter
  • DateHelper

Supports humanized differences and timezone conversion.

✔ Validation & Filtering

Input validation and cleanup utilities.

Includes:

  • Validator
  • Filter
  • ArrayHelper

Supports email, URL, UUID, slug validation and array normalization.

✔ Enums & Constants

Centralized enums and constants used across the ecosystem.

Includes:

  • TextDirectionEnum
  • MessageTypeEnum
  • ErrorCodeEnum
  • PlatformEnum
  • AppEnvironmentEnum
  • EnumHelper

✔ Helper Utilities

General-purpose helpers designed for fluent and expressive code.

TapHelper

Functional-style helper to execute a callback on a value and return the same value unchanged.

Used for:

  • fluent initialization
  • inline configuration
  • readable pipelines

🏗 Design Scope & Architecture

v2.0.0 Architectural Rule

maatify/common must never contain:

  • adapters
  • repositories
  • storage logic
  • Redis / KV abstractions
  • connectivity or DSN handling
  • IO-related behavior
┌──────────────────────────────┐
│        maatify/common        │
│  (helpers, DTOs, enums only) │
└───────────────┬──────────────┘
                │
                ▼
       Infrastructure Packages
       - data-adapters
       - data-repository
       - redis-cache
       - security-guard
       - rate-limiter

This strict boundary guarantees long-term stability and prevents scope creep.

🗂 Directory Structure

src/
├── Pagination/
│   ├── DTO/
│   └── Helpers/
├── Helpers/
│   └── TapHelper.php
├── Security/
│   └── InputSanitizer.php
├── Traits/
│   ├── SingletonTrait.php
│   └── SanitizesInputTrait.php
├── Text/
│   ├── PlaceholderRenderer.php
│   ├── TextFormatter.php
│   ├── RegexHelper.php
│   └── SecureCompare.php
├── Date/
│   ├── DateFormatter.php
│   └── DateHelper.php
└── Validation/
    ├── Validator.php
    ├── Filter.php
    └── ArrayHelper.php

No Contracts/, no Adapters/, no Repository/ directories exist in v2.0.0.

🧪 Testing & Coverage

✔ Current Status (v2.0.0)

  • PHPUnit test suite fully passing
  • ≈98% code coverage
  • PHPStan clean
  • Zero integration dependencies
  • Deterministic behavior across environments

All tests validate pure logic only, without relying on external services.

🔁 Migration Notes (1.x → 2.0.0)

This release introduces intentional breaking changes.

Removed from maatify/common:

  • RepositoryInterface
  • RedisClientInterface
  • KeyValueAdapterInterface
  • ConnectionConfigDTO & ConnectionTypeEnum
  • All adapter / storage / protocol contracts

Migration Path:

Old Usage (1.x) New Location
Repository contracts maatify/data-repository
Redis/KV interfaces maatify/redis-cache / data-adapters
Connection DTOs data-adapters

🪪 License

Released under the MIT License — © 2025 Maatify.dev

Engineered by Mohamed Abdulalim — https://www.maatify.dev Core Architect of the Maatify Backend Ecosystem