Skip to content

Commit 37a244a

Browse files
megyptmmegyptm
committed
feat(helpers): add TapHelper utility with unit tests and README documentation
- Introduced new `TapHelper` class under `Maatify\Common\Helpers` → Provides a fluent, functional-style helper for executing a callback on a given object/value and returning the same instance. - Added `TapHelperTest` to ensure: • Returns the same instance after callback execution • Supports scalars, arrays, and objects • Applies callback effects correctly - Updated README.md: • Added new "🧩 Helper Utilities" section documenting TapHelper usage • Added reference link from Core Modules section • Included code example and architectural benefits This commit enhances developer ergonomics and aligns all Maatify libraries with a consistent functional initialization pattern.
1 parent ba30b77 commit 37a244a

File tree

6 files changed

+432
-7
lines changed

6 files changed

+432
-7
lines changed

‎CHANGELOG.md‎

Lines changed: 118 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,123 @@ This project follows [Semantic Versioning](https://semver.org/).
55

66
---
77

8+
## [1.0.2] – 2025-11-10
9+
10+
### ✨ Helper Utilities Expansion — Introducing `TapHelper`
11+
12+
**Release Date:** 2025-11-10
13+
**Author:** [Mohamed Abdulalim (megyptm)](mailto:mohamed@maatify.dev)
14+
**License:** MIT
15+
**Organization:** [Maatify.dev](https://www.maatify.dev)
16+
17+
---
18+
19+
### ⚙️ Overview
20+
21+
This release introduces **`TapHelper`**, a new functional-style helper utility
22+
that simplifies object initialization and enhances code fluency across all Maatify libraries.
23+
24+
It allows developers to execute a callback on any object or value and return that same value unchanged —
25+
making adapter or service setup more expressive, readable, and concise.
26+
27+
> “Cleaner initialization, consistent patterns, zero boilerplate.”
28+
29+
---
30+
31+
### 🧩 Added
32+
33+
* **New Helper:** `Maatify\Common\Helpers\TapHelper`
34+
35+
* Provides a static `tap()` method to execute a callback on any object or value.
36+
* Returns the same instance unchanged.
37+
* Fully PSR-12 compliant and functional in style.
38+
39+
* **Unit Tests:**
40+
41+
* Added `tests/Helpers/TapHelperTest.php` to verify:
42+
43+
* Object reference equality and immutability.
44+
* Proper callback execution.
45+
* Scalar and array handling.
46+
47+
* **Documentation:**
48+
49+
* Updated `README.md`:
50+
51+
* Added a new **🧩 Helper Utilities** section.
52+
* Included example usage, functional philosophy, and architectural benefits.
53+
* Linked reference from the **Core Modules** section.
54+
55+
---
56+
57+
### 🧱 Architectural Impact
58+
59+
* Promotes **fluent initialization** patterns across all Maatify libraries (`bootstrap`, `data-adapters`, `rate-limiter`, `redis-cache`, etc.).
60+
* Enhances developer ergonomics and readability during service setup.
61+
* Ensures **ecosystem-wide consistency** with other helpers (`PathHelper`, `EnumHelper`, `TimeHelper`).
62+
* Backward compatible with v1.0.1 — no breaking changes introduced.
63+
64+
---
65+
66+
### 🧾 Changelog Snapshot
67+
68+
**v1.0.2 — 2025-11-10**
69+
70+
* Added: `TapHelper` utility under `Maatify\Common\Helpers`.
71+
* Added: Full PHPUnit test coverage for `TapHelper`.
72+
* Updated: `README.md` with new Helper Utilities documentation section.
73+
* Improved: Developer experience for fluent adapter and service initialization.
74+
75+
---
76+
77+
## [1.0.1] – 2025-11-10
78+
79+
### 🧷 Maintenance & Logger Stability Update
80+
81+
**Release Date:** 2025-11-10
82+
**Author:** [Mohamed Abdulalim (megyptm)](mailto:mohamed@maatify.dev)
83+
**License:** MIT
84+
**Organization:** [Maatify.dev](https://www.maatify.dev)
85+
86+
---
87+
88+
### ⚙️ Overview
89+
90+
This maintenance release improves internal logging reliability within the **HybridLockManager**.
91+
A PSR-3 compliant fallback logger is now automatically initialized to prevent `TypeError` exceptions
92+
when no logger instance is injected.
93+
94+
> “Resilient by design — no silent logs, no nulls.”
95+
96+
---
97+
98+
### ✨ Highlights
99+
100+
* **Fixed:** Added PSR-3 `LoggerInterface` fallback in `HybridLockManager`.
101+
* **Improved:** Unified logger initialization using `LoggerContextTrait`.
102+
* **Verified:** All lock-related tests pass on PHP 8.4.4 (98% coverage).
103+
* **Maintained:** Fully backward-compatible with v1.0.0 — no breaking changes.
104+
105+
---
106+
107+
### 🧾 Changelog Snapshot
108+
109+
**v1.0.1 — 2025-11-10**
110+
111+
* Fixed: Logger fallback initialization in `HybridLockManager`.
112+
* Improved: Logging consistency between Redis and File lock drivers.
113+
* Verified: Full test suite passing under PHP 8.4.4.
114+
115+
---
116+
8117
## [1.0.0] – 2025-11-10
9118

10119
### 🎉 First Stable Release
11120

12-
This marks the first official stable release of the **Maatify Common Library**, serving as the foundation for all other Maatify components.
121+
This marks the first official stable release of the **Maatify Common Library**,
122+
serving as the foundation for all other Maatify components.
123+
124+
---
13125

14126
### 🧩 Added
15127

@@ -24,6 +136,8 @@ This marks the first official stable release of the **Maatify Common Library**,
24136
* **Documentation** — detailed Markdown docs for all modules under `/docs/`.
25137
* **Unit Tests** — comprehensive PHPUnit coverage (>95%) across all components.
26138

139+
---
140+
27141
### ⚙️ Internal
28142

29143
* Full **PSR-12** compliance and strict typing (`declare(strict_types=1);`).
@@ -42,4 +156,6 @@ for all future Maatify modules such as `maatify/psr-logger`, `maatify/rate-limit
42156
---
43157

44158
**© 2025 Maatify.dev** — Engineered by [Mohamed Abdulalim](https://www.maatify.dev)
45-
Distributed under the [MIT License](LICENSE).
159+
Distributed under the [MIT License](LICENSE)
160+
161+
---

‎README-AR.md‎

Lines changed: 88 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
![**Maatify.dev**](https://www.maatify.dev/assets/img/img/maatify_logo_white.svg)
2+
23
---
4+
5+
# 📦 maatify/common
6+
37
[![Version](https://img.shields.io/packagist/v/maatify/common?label=Version&color=4C1)](https://packagist.org/packages/maatify/common)
48
[![PHP](https://img.shields.io/packagist/php-v/maatify/common?label=PHP&color=777BB3)](https://packagist.org/packages/maatify/common)
59
[![Build](https://github.com/Maatify/common/actions/workflows/ci.yml/badge.svg?label=Build&color=brightgreen)](https://github.com/Maatify/common/actions/workflows/ci.yml)
@@ -12,8 +16,6 @@
1216

1317
---
1418

15-
# 📦 maatify/common
16-
1719
🏁 **الإصدار المستقر v1.0.0** — المكتبة الأساسية الجوهرية لمنظومة **Maatify.dev**، والتي توفر أدوات قياسية مثل DTOs، التحقق (Validation)، التعقيم (Sanitization)، التاريخ والوقت (Date/Time)، أنظمة القفل (Locking)، وأدوات النصوص (Text Utilities) لجميع الوحدات الخلفية (Backend Modules).
1820

1921
> 📦 هذا هو أول إصدار رسمي مستقر **(v1.0.0)** من مكتبة `maatify/common`، الصادر بتاريخ **10 نوفمبر 2025**.
@@ -819,6 +821,90 @@ src/Constants/
819821
├── CommonHeaders.php
820822
└── Defaults.php
821823
```
824+
---
825+
826+
## 🧩 المساعدات (Helpers)
827+
828+
### 🧱 TapHelper
829+
830+
أداة خفيفة وسلسة تُستخدم لتنفيذ دالة (callback) على قيمة أو كائن ثم إرجاع نفس القيمة بدون تغيير —
831+
مفيدة جدًا لجعل عملية تهيئة الكائنات أكثر أناقة وتنظيمًا.
832+
833+
---
834+
835+
#### ⚙️ الكلاس
836+
`Maatify\Common\Helpers\TapHelper`
837+
838+
#### ✅ المميزات
839+
- تنفّذ دالة على كائن أو قيمة يتم تمريرها.
840+
- تُرجع نفس القيمة (سواء كانت كائن، رقم، مصفوفة، إلخ...).
841+
- مثالية لأسلوب البرمجة السلس (Fluent API).
842+
- لا تغيّر القيمة الأصلية إلا إذا غيّرتها الدالة نفسها.
843+
844+
---
845+
846+
#### 🧠 مثال للاستخدام
847+
```php
848+
use Maatify\Common\Helpers\TapHelper;
849+
use Maatify\DataAdapters\Adapters\MongoAdapter;
850+
851+
$config = new EnvironmentConfig(__DIR__ . '/../');
852+
853+
$mongo = TapHelper::tap(new MongoAdapter($config), fn($a) => $a->connect());
854+
855+
// $mongo الآن عبارة عن Adapter متصل فعليًا
856+
$client = $mongo->getConnection();
857+
````
858+
859+
---
860+
861+
#### 🧾 الفلسفة الوظيفية
862+
863+
`TapHelper` يتّبع أسلوبًا بسيطًا وواضحًا مستوحى من البرمجة الوظيفية (Functional Programming):
864+
865+
| المبدأ | الوصف |
866+
|--------------------------------------|----------------------------------------------------------|
867+
| 🧩 **العزل (Isolation)** | يتم تنفيذ الدالة بمعزل عن السياق الخارجي ولا تُرجع قيمة. |
868+
| 🔁 **الثبات (Immutability)** | تُعاد القيمة الأصلية بدون تغيير. |
869+
| 🧼 **الوضوح (Clarity)** | يقلل من الأكواد المتكررة أثناء تهيئة الكائنات. |
870+
| 🧠 **قابلية الاختبار (Testability)** | سهل الفهم والاختبار (راجع `TapHelperTest`). |
871+
872+
---
873+
874+
#### 🧪 اختبار الوحدة
875+
876+
`tests/Helpers/TapHelperTest.php`
877+
878+
يغطي:
879+
880+
* التحقق من إرجاع نفس الكائن.
881+
* التأكد من تنفيذ الدالة بشكل صحيح.
882+
* دعم القيم المختلفة (كائنات – Scalars – مصفوفات).
883+
884+
```bash
885+
vendor/bin/phpunit --filter TapHelperTest
886+
```
887+
888+
---
889+
890+
#### 🧱 المرجع البرمجي
891+
892+
```php
893+
TapHelper::tap(mixed $value, callable $callback): mixed
894+
```
895+
896+
> ينفّذ `$callback($value)` ثم يُرجع `$value`.
897+
898+
---
899+
900+
#### 🧩 الفوائد المعمارية داخل منظومة Maatify
901+
902+
| الجانب | الفائدة |
903+
|-------------------------------------------------------|--------------------------------------------------------------------------------------------------------|
904+
| ♻️ **تهيئة سلسة (Fluent Initialization)** | يتيح إنشاء adapters أو الخدمات بسطر واحد أنيق. |
905+
| 🧠 **اتساق ضمن النظام (Ecosystem Consistency)** | متوافق في الفلسفة مع أدوات مثل `PathHelper` و `EnumHelper` و `TimeHelper`. |
906+
| 🧼 **تقليل التكرار (Reduced Boilerplate)** | يستبدل عدة أسطر إعداد بسطر واحد واضح وسهل القراءة. |
907+
| 🧩 **قابلية إعادة الاستخدام (Universal Reusability)** | يعمل بسلاسة مع جميع مكتبات Maatify (`bootstrap`, `data-adapters`, `rate-limiter`, `redis-cache`, ...). |
822908
823909
---
824910

‎README.md‎

Lines changed: 90 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
![**Maatify.dev**](https://www.maatify.dev/assets/img/img/maatify_logo_white.svg)
2+
23
---
4+
5+
# 📦 maatify/common
6+
37
[![Version](https://img.shields.io/packagist/v/maatify/common?label=Version&color=4C1)](https://packagist.org/packages/maatify/common)
48
[![PHP](https://img.shields.io/packagist/php-v/maatify/common?label=PHP&color=777BB3)](https://packagist.org/packages/maatify/common)
59
[![Build](https://github.com/Maatify/common/actions/workflows/ci.yml/badge.svg?label=Build&color=brightgreen)](https://github.com/Maatify/common/actions/workflows/ci.yml)
@@ -12,8 +16,6 @@
1216

1317
---
1418

15-
# 📦 maatify/common
16-
1719
🏁 Stable Release v1.0.0 — The core foundational library of the Maatify.dev ecosystem providing standardized DTOs, validation, sanitization, date/time, locking, and text utilities for all backend modules.
1820
> 📦 This is the first official stable version (v1.0.0) of maatify/common, released on **2025-11-10**.
1921
@@ -721,6 +723,90 @@ src/Constants/
721723
├── CommonHeaders.php
722724
└── Defaults.php
723725
```
726+
---
727+
## 🧩 Helpers
728+
729+
### 🧱 TapHelper
730+
731+
A lightweight, fluent utility for executing a callback on a given value (usually an object) and returning that same value unchanged —
732+
perfect for cleaner object initialization and inline setup.
733+
734+
---
735+
736+
#### ⚙️ Class
737+
`Maatify\Common\Helpers\TapHelper`
738+
739+
#### ✅ Features
740+
- Executes a callback on a passed object or value.
741+
- Returns the same value (object, scalar, array, etc.).
742+
- Useful for chaining and fluent API style.
743+
- 100% pure function — no side effects unless your callback modifies the object.
744+
745+
---
746+
747+
#### 🧠 Example Usage
748+
```php
749+
use Maatify\Common\Helpers\TapHelper;
750+
use Maatify\DataAdapters\Adapters\MongoAdapter;
751+
752+
$config = new EnvironmentConfig(__DIR__ . '/../');
753+
754+
$mongo = TapHelper::tap(new MongoAdapter($config), fn($a) => $a->connect());
755+
756+
// $mongo is now a connected adapter
757+
$client = $mongo->getConnection();
758+
````
759+
760+
---
761+
762+
#### 🧾 Functional Philosophy
763+
764+
`TapHelper` follows a simple, expressive pattern inspired by functional programming:
765+
766+
| Principle | Description |
767+
|---------------------|-------------------------------------------------------------|
768+
| 🧩 **Isolation** | The callback runs in isolation, returning no value. |
769+
| 🔁 **Immutability** | The original object/value is returned unchanged. |
770+
| 🧼 **Clarity** | Reduces boilerplate for setup code. |
771+
| 🧠 **Testability** | Simple to reason about and unit-test (see `TapHelperTest`). |
772+
773+
---
774+
775+
#### 🧪 Unit Test Reference
776+
777+
`tests/Helpers/TapHelperTest.php`
778+
779+
Covers:
780+
781+
* Returning the same object instance.
782+
* Callback execution correctness.
783+
* Compatibility with scalars and arrays.
784+
785+
```bash
786+
vendor/bin/phpunit --filter TapHelperTest
787+
```
788+
789+
---
790+
791+
#### 🧱 Code Reference
792+
793+
```php
794+
TapHelper::tap(mixed $value, callable $callback): mixed
795+
```
796+
797+
> Executes `$callback($value)` then returns `$value`.
798+
799+
---
800+
801+
#### 🧩 Architectural Benefits within the Maatify Ecosystem
802+
803+
| Aspect | Benefit |
804+
|------------------------------|--------------------------------------------------------------------------------------------------------------------|
805+
| ♻️ **Fluent Initialization** | Enables building adapters and services in one clean line. |
806+
| 🧠 **Ecosystem Consistency** | Aligns with other helpers like `PathHelper`, `EnumHelper`, and `TimeHelper`. |
807+
| 🧼 **Reduced Boilerplate** | Replaces multiple setup lines with a single expressive call. |
808+
| 🧩 **Universal Reusability** | Works seamlessly across all Maatify libraries (`bootstrap`, `data-adapters`, `rate-limiter`, `redis-cache`, etc.). |
809+
724810

725811
---
726812

@@ -738,6 +824,8 @@ src/
738824
│ └── Helpers/
739825
│ ├── PaginationHelper.php
740826
│ └── PaginationResultDTO.php
827+
├── Helpers/
828+
│ └── TapHelper.php
741829
├── Lock/
742830
│ ├── LockInterface.php
743831
│ ├── LockModeEnum.php

‎VERSION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
1.0.0
1+
1.0.2

0 commit comments

Comments
 (0)