Maatify.dev

Version PHP License Status

Build PHPStan Code Quality

Monthly Downloads Total Downloads Stars

Changelog Security Full Docs Contributing

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}