The core foundational library of the Maatify.dev ecosystem providing standardized DTOs, validation, sanitization, date/time, text utilities, and shared core helpers.

📦 This is the stable version (v1.0.10) of maatify/common, released on 2025-12-09. 🔗 بالعربي 🇸🇦

This library provides reusable, framework-agnostic building blocks (DTOs, helpers, traits, enums, validators) shared across the Maatify ecosystem.

• 🧮 Pagination Helpers — PaginationHelper, PaginationDTO, PaginationResultDTO Unified pagination structures for API responses and MySQL queries.

• 🧼 Security Sanitization — InputSanitizer, SanitizesInputTrait Clean and escape user input safely with internal HTMLPurifier integration.

• 🧠 Core Traits — SingletonTrait, SanitizesInputTrait Reusable traits for singleton pattern, safe input handling, and shared helpers.

• ✨ Text & Placeholder Utilities — TextFormatter, PlaceholderRenderer, RegexHelper, SecureCompare Powerful text formatting, placeholder rendering, and secure string comparison tools.

• 🕒 Date & Time Utilities — DateFormatter, DateHelper Humanized difference, timezone conversion, and localized date rendering (EN/AR/FR).

• 🧩 Validation & Filtering Tools — Validator, Filter, ArrayHelper Email/URL/UUID/Slug validation, input detection, and advanced array cleanup utilities.

• ⚙️ Enums & Constants Standardization — TextDirectionEnum, MessageTypeEnum, ErrorCodeEnum, PlatformEnum, AppEnvironmentEnum, CommonPaths, CommonLimits, CommonHeaders, Defaults, EnumHelper Centralized enum and constant definitions ensuring consistent standards, reusable helpers, and unified configuration across all Maatify libraries.

⚠️ Design Scope Notice

maatify/common is intentionally limited to pure helpers, DTOs, traits, enums, and shared utilities.

It contains no adapters, repositories, drivers, storage contracts, or IO-related abstractions. Any such responsibilities belong to dedicated infrastructure packages.

composer require maatify/common

This library directly relies on:

maatify/common integrates these open-source libraries to deliver a consistent and secure foundation for all other Maatify components.

🧠 Note: maatify/common automatically configures HTMLPurifier to use an internal cache directory at storage/purifier_cache for optimized performance. This ensures faster sanitization on subsequent calls without requiring manual setup.

If you wish to override the cache path, set the environment variable:

HTMLPURIFIER_CACHE_PATH=/path/to/custom/cache

or modify it programmatically via:

$config->set('Cache.SerializerPath', '/custom/cache/path');

A clean, PSR-friendly Singleton implementation to manage single-instance service classes safely.

use Maatify\Common\Traits\SingletonTrait;

final class ConfigManager
{
    use SingletonTrait;

    public function get(string $key): ?string
    {
        return $_ENV[$key] ?? null;
    }
}

// ✅ Always returns the same instance
$config = ConfigManager::obj();

// ♻️ Reset (for testing)
ConfigManager::reset();

• Prevents direct construction, cloning, and unserialization.
• Provides static obj() to access the global instance.
• Includes reset() for testing or reinitialization.

use Maatify\Common\Pagination\Helpers\PaginationHelper;

$items = range(1, 100);

$result = PaginationHelper::paginate($items, page: 2, perPage: 10);

print_r($result);

Output:

[
    'data' => [11, 12, 13, 14, 15, 16, 17, 18, 19, 20],
    'pagination' => Maatify\Common\DTO\PaginationDTO {
        page: 2,
        perPage: 10,
        total: 100,
        totalPages: 10,
        hasNext: true,
        hasPrev: true
    }
]

use Maatify\Common\Pagination\DTO\PaginationDTO;

$pagination = new PaginationDTO(
    page: 1,
    perPage: 25,
    total: 200,
    totalPages: 8,
    hasNext: true,
    hasPrev: false
);

print_r($pagination->toArray());

A lightweight, fluent utility for executing a callback on a given value (usually an object) and returning that same value unchanged —
perfect for cleaner object initialization and inline setup.

Maatify\Common\Helpers\TapHelper

• Executes a callback on a passed object or value.
• Returns the same value (object, scalar, array, etc.).
• Useful for chaining and fluent API style.
• 100% pure function — no side effects unless your callback modifies the object.

use Maatify\Common\Helpers\TapHelper;
use Maatify\DataAdapters\Adapters\MongoAdapter;

$config = new EnvironmentConfig(__DIR__ . '/../');

$mongo = TapHelper::tap(new MongoAdapter($config), fn($a) => $a->connect());

// $mongo is now a connected adapter
$client = $mongo->getConnection();

TapHelper follows a simple, expressive pattern inspired by functional programming:

tests/Helpers/TapHelperTest.php

Covers:

• Returning the same object instance.
• Callback execution correctness.
• Compatibility with scalars and arrays.

vendor/bin/phpunit --filter TapHelperTest

TapHelper::tap(mixed $value, callable $callback): mixed

Executes $callback($value) then returns $value.

📘 Full Documentation: docs/enums.md

src/
├── Pagination/
│   ├── DTO/
│   │   └── PaginationDTO.php
│   └── Helpers/
│       ├── PaginationHelper.php
│       └── PaginationResultDTO.php
├── 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
        Enums/
        ├── TextDirectionEnum.php
        ├── MessageTypeEnum.php
        ├── ErrorCodeEnum.php
        ├── PlatformEnum.php
        ├── AppEnvironmentEnum.php
        ├── EnumHelper.php
        └── Traits/
            └── EnumJsonSerializableTrait.php

maatify/common proudly builds upon several mature and battle-tested open-source foundations:

Huge thanks to the open-source community for their contributions, making the Maatify ecosystem secure, reliable, and extensible. ❤️

PHPUnit 10.5.58 — PHP 8.4.4
• Tests: 66 • Assertions: 150 • Coverage: ~98 %
• Runtime: 0.076 s • Memory: 12 MB
• Warnings: 1 (No coverage driver available — safe to ignore)

All files have been verified and finalized as part of v2.0.0 Stable Release.

• ✅ /docs/README.full.md – full documentation merged
• ✅ /docs/enums.md – enums and constants reference
• ✅ /docs/phases/README.phase7.md – phase documentation
• ✅ CHANGELOG.md – release history initialized
• ✅ CONTRIBUTING.md – contributor guide added
• ✅ VERSION – version 2.0.0 confirmed

🔗 Full documentation & release notes: see /docs/README.full.md

MIT license © Maatify.dev
You’re free to use, modify, and distribute this library with attribution.

This library is part of the Maatify.dev Core Ecosystem, designed and maintained under the technical supervision of:

👤 Mohamed Abdulalim — Backend Lead & Technical Architect
Lead architect of the Maatify Backend Infrastructure, responsible for the overall architecture, core library design,
and technical standardization across all backend modules within the Maatify ecosystem.
🔗 www.Maatify.dev | ✉️ mohamed@maatify.dev

🤝 Contributors:
The Maatify.dev Engineering Team and open-source collaborators who continuously help refine, test, and extend
the capabilities of this library across multiple Maatify projects.

🧩 This project represents a unified engineering effort led by Mohamed Abdulalim, ensuring every Maatify backend component
shares a consistent, secure, and maintainable foundation.

Built with ❤️ by Maatify.dev — Unified Ecosystem for Modern PHP Libraries