PHPackages                             maatify/common - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. maatify/common

ActiveLibrary[Utility & Helpers](/categories/utility)

maatify/common
==============

Common DTOs and helpers for all maatify libraries

v2.0.0(5mo ago)186215MITPHPPHP >=8.2CI passing

Since Nov 10Pushed 5mo agoCompare

[ Source](https://github.com/Maatify/common)[ Packagist](https://packagist.org/packages/maatify/common)[ RSS](/packages/maatify-common/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (8)Versions (13)Used By (5)

[![Maatify.dev](https://camo.githubusercontent.com/bb8bf9ee079d7f823c9d5e94061d1d4c11dc0898e2b1b5cc9a8a7b04d8bfdd7d/68747470733a2f2f7777772e6d6161746966792e6465762f6173736574732f696d672f696d672f6d6161746966795f6c6f676f5f77686974652e737667)](https://camo.githubusercontent.com/bb8bf9ee079d7f823c9d5e94061d1d4c11dc0898e2b1b5cc9a8a7b04d8bfdd7d/68747470733a2f2f7777772e6d6161746966792e6465762f6173736574732f696d672f696d672f6d6161746966795f6c6f676f5f77686974652e737667)

---

📦 maatify/common
================

[](#-maatifycommon)

[![Version](https://camo.githubusercontent.com/6009302cc4f9a83c81a76de39911c2adcf8f1091099f027ad1baf356c8dd6f3e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d6161746966792f636f6d6d6f6e3f6c6162656c3d56657273696f6e26636f6c6f723d344331267374796c653d666c61742d737175617265)](https://packagist.org/packages/maatify/common)[![PHP](https://camo.githubusercontent.com/14c3fbb6659f22b59e571b5e55a629573e356d79556b39f123850d880c409f6e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6d6161746966792f636f6d6d6f6e3f6c6162656c3d50485026636f6c6f723d373737424233267374796c653d666c61742d737175617265)](https://packagist.org/packages/maatify/common)[![License](https://camo.githubusercontent.com/79aaa7c5111c7246bc06600bf4564de7583dfb5385e997e820cfd57c39d2fe63/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f4d6161746966792f636f6d6d6f6e3f6c6162656c3d4c6963656e736526636f6c6f723d626c756576696f6c6574267374796c653d666c61742d737175617265)](LICENSE)[![Status](https://camo.githubusercontent.com/2128a821a9f55f8f5e5806efa8de7dfe863140215ec85b68a1d4301610cfdd32/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5374617475732d537461626c652d737563636573733f7374796c653d666c61742d737175617265)](CHANGELOG.md)

[![Build](https://github.com/Maatify/common/actions/workflows/ci.yml/badge.svg?style=flat-square)](https://github.com/Maatify/common/actions/workflows/ci.yml)[![PHPStan](https://camo.githubusercontent.com/500c8c790f0197ef4bd61e6277ba1cba3e568c20e04091aaf896bfb49df7a2dd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d4c6576656c253230362d3445384341453f7374796c653d666c61742d737175617265)](https://phpstan.org/)[![Code Quality](https://camo.githubusercontent.com/1bd094581a3d75e4cd1c5408fe9a671c4543dbb4ea4472cabf1baa3a360bdc67/68747470733a2f2f696d672e736869656c64732e696f2f636f6465666163746f722f67726164652f6769746875622f4d6161746966792f636f6d6d6f6e2f6d61696e3f636f6c6f723d627269676874677265656e267374796c653d666c61742d737175617265)](https://www.codefactor.io/repository/github/Maatify/common)

[![Monthly Downloads](https://camo.githubusercontent.com/866ca98ac6977db57c33e922783f12f633a8c9f5cc5e9a5f882300506414a714/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f6d6161746966792f636f6d6d6f6e3f6c6162656c3d4d6f6e74686c79253230446f776e6c6f61647326636f6c6f723d303041384538267374796c653d666c61742d737175617265)](https://packagist.org/packages/maatify/common)[![Total Downloads](https://camo.githubusercontent.com/c4a11959198181e93c8550d562ddd31d7accfea6b280a25650944e37554732bc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d6161746966792f636f6d6d6f6e3f6c6162656c3d546f74616c253230446f776e6c6f61647326636f6c6f723d324141394530267374796c653d666c61742d737175617265)](https://packagist.org/packages/maatify/common)[![Stars](https://camo.githubusercontent.com/13bf1594bad2a48ba6aab32042f8a193d84e7b735573ba06a344815e5dcefa60/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f4d6161746966792f636f6d6d6f6e3f6c6162656c3d537461727326636f6c6f723d4646443433422663616368655365636f6e64733d33363030267374796c653d666c61742d737175617265)](https://github.com/Maatify/common/stargazers)

[![Changelog](https://camo.githubusercontent.com/3a71e94b4a2d07d2bf4ab7a2ea5d0adc7ddb35bde00309f449754e669c86c84b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4368616e67656c6f672d566965772d626c75653f7374796c653d666c61742d737175617265)](CHANGELOG.md)[![Security](https://camo.githubusercontent.com/922ef7224cb3fb11acf628ca9a4bbe034201bc4b4ba812fd150428a1955906d8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53656375726974792d506f6c6963792d696d706f7274616e743f7374796c653d666c61742d737175617265)](SECURITY.md)[![Full Docs](https://camo.githubusercontent.com/e7666e228c56feeb538b7ce103257c78d42b3775b3280a81857afd4dee071ac5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f446f63732d46756c6c25323047756964652d3041363643323f7374796c653d666c61742d737175617265)](docs/README.full.md)[![Contributing](https://camo.githubusercontent.com/8648aa8f72f276d4ffef8ef88bae6eeb081576e811fc40933f14771f211f0fb4/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f436f6e747269627574696e672d47756964652d3041393339363f7374796c653d666c61742d737175617265)](CONTRIBUTING.md)

---

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

[](#-stable-release-v200--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**. 🔗 [بالعربي 🇸🇦 ](./README-AR.md)

---

🧭 Version Information
---------------------

[](#-version-information)

KeyValueVersion**2.0.0 Stable**Release Date2025-12-17PHP Requirement≥ 8.2LicenseMITCoverage98 %Tests Passed70+ (160+ Assertions)---

🧩 Overview
----------

[](#-overview)

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

---

📘 Documentation & Release Files
-----------------------------------

[](#-documentation--release-files)

FileDescription`/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:**
-----------------

[](#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
---------------

[](#️-installation)

```
composer require maatify/common
```

---

📦 Dependencies
--------------

[](#-dependencies)

This library directly relies on:

DependencyPurposeLink**ezyang/htmlpurifier**Secure HTML/XSS sanitization engine[github.com/ezyang/htmlpurifier](https://github.com/ezyang/htmlpurifier)**psr/log**Standardized PSR-3 logging interface[www.php-fig.org/psr/psr-3](https://www.php-fig.org/psr/psr-3/)**phpunit/phpunit**Unit testing framework (development only)[phpunit.de](https://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
----------------

[](#-singletontrait)

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

### 🔹 Example Usage

[](#-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

[](#-features)

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

---

📚 Example Usage
---------------

[](#-example-usage-1)

### 🔹 Paginate Array Data

[](#-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`

[](#-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
---------

[](#-helpers)

### 🧱 TapHelper

[](#-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

[](#️-class)

`Maatify\Common\Helpers\TapHelper`

#### ✅ Features

[](#-features-1)

- 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

[](#-example-usage-2)

```
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

[](#-functional-philosophy)

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

PrincipleDescription🧩 **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

[](#-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

[](#-code-reference)

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

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

---

#### 🧩 Architectural Benefits within the Maatify Ecosystem

[](#-architectural-benefits-within-the-maatify-ecosystem)

AspectBenefit♻️ **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](docs/enums.md)

---

🗂 Directory Structure
---------------------

[](#-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
------------

[](#-built-upon)

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

LibraryDescriptionUsage in Project**[ezyang/htmlpurifier](https://github.com/ezyang/htmlpurifier)**Standards-compliant HTML filtering libraryPowers `InputSanitizer` to ensure XSS-safe and standards-compliant HTML output with full Unicode support.**[psr/log](https://www.php-fig.org/psr/psr-3/)**PSR-3 logging interfaceEnables standardized logging across sanitization, and validation components.**[phpunit/phpunit](https://phpunit.de)**PHP unit testing frameworkProvides 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)**
===================================================

[](#--updated-phase-summary-table-phases-1--18)

PhaseTitleStatusFiles CreatedNotes1Pagination Module✅ Completed3Pagination DTOs & helpers3Security & Input Sanitization✅ Completed3InputCleaner, HTMLPurifier wrapper, XSS-safe normalizers3bCore Traits — Singleton System✅ Completed1SingletonTrait implementation4Text & Placeholder Utilities✅ Completed8PlaceholderRenderer, TextFormatter, RegexHelper, SecureCompare5Date & Time Utilities✅ Completed4HumanizeDifference, LocalizedDateFormatter, Timestamp helpers6Validation & Filtering Tools✅ Completed3Validator, Filter, ArrayHelper + full PHPUnit suite7Enums & Constants Standardization✅ Completed10 + 5 testsUnified Enum system, EnumHelper, JSONSerializableTrait, ValueEnum base8Testing & Release (v1.0.0)✅ Completed6CHANGELOG, CONTRIBUTING, VERSION, README.full.md, CI integration, initial stable release10TapHelper Utility✅ Completed1Introduced TapHelper + full test coverage12Version Hotfix✅ Completed1Fixed version mismatch and updated VERSION file---

✅ Verified Test Results
-----------------------

[](#-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](docs/README.full.md)

---

🪪 License
---------

[](#-license)

**[MIT license](LICENSE)** © [Maatify.dev](https://www.maatify.dev)
You’re free to use, modify, and distribute this library with attribution.

---

🧱 Authors & Credits
-----------------------

[](#-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](https://www.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](https://www.maatify.dev) — Unified Ecosystem for Modern PHP Libraries

---

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance73

Regular maintenance activity

Popularity16

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

12

Last Release

151d ago

Major Versions

v1.0.10 → v2.0.02025-12-17

PHP version history (2 changes)v1.0.0PHP >=8.4

v2.0.0PHP >=8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/1a885a0810f2762586520ab284c9019aaf0b650b53cdf2a6c13ea10931bb7795?d=identicon)[Maatify](/maintainers/Maatify)

---

Top Contributors

[![megyptm](https://avatars.githubusercontent.com/u/33574895?v=4)](https://github.com/megyptm "megyptm (75 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/maatify-common/health.svg)

```
[![Health](https://phpackages.com/badges/maatify-common/health.svg)](https://phpackages.com/packages/maatify-common)
```

###  Alternatives

[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

728272.9k20](/packages/civicrm-civicrm-core)[caxy/php-htmldiff

A library for comparing two HTML files/snippets and highlighting the differences using simple HTML.

21520.9M15](/packages/caxy-php-htmldiff)[getdkan/dkan

DKAN Open Data Catalog

385135.4k2](/packages/getdkan-dkan)[verbb/formie

The most user-friendly forms plugin for Craft.

101372.9k40](/packages/verbb-formie)[stevebauman/hypertext

The best HTML to text transformer

171472.6k2](/packages/stevebauman-hypertext)[trsteel/ckeditor-bundle

Symfony bundle for easy integration of the CKEditor WYSIWYG

99630.9k9](/packages/trsteel-ckeditor-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)