maatify/common

Common DTOs and helpers for all maatify libraries

v2.0.0 2025-12-17 15:36 UTC

Requires

• php: >=8.2
• ext-intl: *
• ext-mbstring: *
• ezyang/htmlpurifier: ^4.19
• maatify/psr-logger: ^1.0

Requires (Dev)

• doctrine/dbal: ^4.3
• friendsofphp/php-cs-fixer: ^3.89
• mongodb/mongodb: ^2.0
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^11.0
• predis/predis: ^2.3

MIT

• Maatify.dev

README

📦 maatify/common

🏁 Stable Release v2.0.0 — Architectural Cleanup & Scope Stabilization

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. 🔗 بالعربي 🇸🇦

🧭 Version Information

Key	Value
Version	2.0.0 Stable
Release Date	2025-12-17
PHP Requirement	≥ 8.2
License	MIT
Coverage	98 %
Tests Passed	70+ (160+ Assertions)

🧩 Overview

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

📘 Documentation & Release Files

File	Description
/docs/README.full.md	Full documentation (Phases 1–13)
/docs/enums.md	Enums & constants reference
CHANGELOG.md	Version history (updated to 2.0.0)
CONTRIBUTING.md	Contribution guidelines
VERSION	Current version → 2.0.0

Core Modules:

• 🧮 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.

⚙️ Installation

composer require maatify/common

📦 Dependencies

This library directly relies on:

Dependency	Purpose	Link
ezyang/htmlpurifier	Secure HTML/XSS sanitization engine	github.com/ezyang/htmlpurifier
psr/log	Standardized PSR-3 logging interface	www.php-fig.org/psr/psr-3
phpunit/phpunit	Unit testing framework (development only)	phpunit.de

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');

🧠 SingletonTrait

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

🔹 Example Usage

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();

✅ Features

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

📚 Example Usage

🔹 Paginate Array Data

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
    }
]

🔹 Working with PaginationDTO

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());

🧩 Helpers

🧱 TapHelper

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.

⚙️ Class

Maatify\Common\Helpers\TapHelper

✅ Features

• 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.

🧠 Example Usage

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();

🧾 Functional Philosophy

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

Principle	Description
🧩 Isolation	The callback runs in isolation, returning no value.
🔁 Immutability	The original object/value is returned unchanged.
🧼 Clarity	Reduces boilerplate for setup code.
🧠 Testability	Simple to reason about and unit-test (see TapHelperTest).

🧪 Unit Test Reference

tests/Helpers/TapHelperTest.php

Covers:

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

vendor/bin/phpunit --filter TapHelperTest

🧱 Code Reference

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

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

🧩 Architectural Benefits within the Maatify Ecosystem

Aspect	Benefit
♻️ Fluent Initialization	Enables building adapters and services in one clean line.
🧠 Ecosystem Consistency	Aligns with other helpers like PathHelper, EnumHelper, and TimeHelper.
🧼 Reduced Boilerplate	Replaces multiple setup lines with a single expressive call.
🧩 Universal Reusability	Works seamlessly across all Maatify libraries (bootstrap, data-adapters, rate-limiter, redis-cache, etc.).

📘 Full Documentation: docs/enums.md

🗂 Directory Structure

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

📚 Built Upon

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

Library	Description	Usage in Project
ezyang/htmlpurifier	Standards-compliant HTML filtering library	Powers InputSanitizer to ensure XSS-safe and standards-compliant HTML output with full Unicode support.
psr/log	PSR-3 logging interface	Enables standardized logging across sanitization, and validation components.
phpunit/phpunit	PHP unit testing framework	Provides automated testing with CI/CD GitHub workflow integration.

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

✅ 📊 Updated Phase Summary Table (Phases 1 → 18)

Phase	Title	Status	Files Created	Notes
1	Pagination Module	✅ Completed	3	Pagination DTOs & helpers
3	Security & Input Sanitization	✅ Completed	3	InputCleaner, HTMLPurifier wrapper, XSS-safe normalizers
3b	Core Traits — Singleton System	✅ Completed	1	SingletonTrait implementation
4	Text & Placeholder Utilities	✅ Completed	8	PlaceholderRenderer, TextFormatter, RegexHelper, SecureCompare
5	Date & Time Utilities	✅ Completed	4	HumanizeDifference, LocalizedDateFormatter, Timestamp helpers
6	Validation & Filtering Tools	✅ Completed	3	Validator, Filter, ArrayHelper + full PHPUnit suite
7	Enums & Constants Standardization	✅ Completed	10 + 5 tests	Unified Enum system, EnumHelper, JSONSerializableTrait, ValueEnum base
8	Testing & Release (v1.0.0)	✅ Completed	6	CHANGELOG, CONTRIBUTING, VERSION, README.full.md, CI integration, initial stable release
10	TapHelper Utility	✅ Completed	1	Introduced TapHelper + full test coverage
12	Version Hotfix	✅ Completed	1	Fixed version mismatch and updated VERSION file

✅ Verified Test Results

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

🪪 License

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

🧱 Authors & Credits

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 | ✉️ [e-mail]

🤝 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}