feat: add ConnectionTypeEnum and ConnectionConfigDTO to support DSN-based resolution

- Introduced ConnectionTypeEnum for normalized adapter types
- Added ConnectionConfigDTO to unify connection configuration structure
- Updated internal documentation and prepared for DSN routing in data-adapters
- Part of Phase 10 preparation (maatify/data-adapters)

Author: megyptm

CHANGELOG.md

@@ -3,6 +3,91 @@
 All notable changes to **maatify/common** will be documented in this file.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.0.3] – 2025-11-13
+
+### 🧩 Connectivity Foundation — Introducing `ConnectionConfigDTO` & `ConnectionTypeEnum`
+
+**Release Date:** 2025-11-13
+**Author:** [Mohamed Abdulalim (megyptm)](mailto:mohamed@maatify.dev)
+**License:** MIT
+**Organization:** [Maatify.dev](https://www.maatify.dev)
+
+---
+
+### ⚙️ Overview
+
+This update introduces two new standardized components that will be used across all Maatify backend libraries:
+
+* **`ConnectionConfigDTO`** — a readonly DTO that encapsulates driver-specific connection settings.
+* **`ConnectionTypeEnum`** — a unified enum for all supported connection types (`mysql`, `mongo`, `redis`).
+
+These additions support the new DSN-based workflow planned in `maatify/data-adapters` (Phase 10)
+and enforce consistency across the Maatify ecosystem.
+
+> “One connection model — shared across all libraries.”
+
+---
+
+### 🧩 Added
+
+#### ✔ `Maatify\Common\DTO\ConnectionConfigDTO`
+
+* Readonly object representing:
+
+    * `driver`
+    * `dsn`
+    * `user`
+    * `pass`
+    * `options`
+    * `profile` (supports multiple DSN profiles in future releases)
+* Basis for profile-based DSN resolution in data-adapters.
+
+#### ✔ `Maatify\Common\Enums\ConnectionTypeEnum`
+
+* Defines consistent adapter identifiers:
+
+    * `MYSQL`
+    * `MONGO`
+    * `REDIS`
+
+#### ✔ New Tests
+
+* Added test suite:
+
+    * `tests/DTO/ConnectionConfigDTOTest.php`
+    * `tests/Enums/ConnectionTypeEnumTest.php`
+* Verified:
+
+    * DTO immutability
+    * Enum integrity
+    * PSR-12 compliance
+
+#### ✔ Documentation Update
+
+* Updated `/docs/core/helpers.md`
+  → Added new section: **Connectivity Foundation**
+* Linked from main README under **Core Modules**
+
+---
+
+### 🧱 Architectural Impact
+
+* Establishes a **shared foundation** for database configurations.
+* Required for **Phase 10** in `maatify/data-adapters` (string-based driver selection + DSN builder).
+* Ensures **cross-library consistency** for all future adapters and DI containers.
+
+---
+
+### 🧾 Changelog Snapshot
+
+**v1.0.3 — 2025-11-13**
+
+* Added: `ConnectionConfigDTO`
+* Added: `ConnectionTypeEnum`
+* Added: Tests for DTO & Enum
+* Updated: Docs with new Connectivity Foundation section
+* No breaking changes — Fully backward compatible
+
 ---
 
 ## [1.0.2] – 2025-11-10

release-note.md

@@ -0,0 +1,67 @@
+<?php
+/**
+ * @copyright   ©2025 Maatify.dev
+ * @Library     maatify/common
+ * @Project     maatify:common
+ * @author      Mohamed Abdulalim (megyptm) <mohamed@maatify.dev>
+ * @since       2025-11-13 16:17
+ * @see         https://www.maatify.dev Maatify.com
+ * @link        https://github.com/Maatify/common  view project on GitHub
+ * @note        Distributed in the hope that it will be useful - WITHOUT WARRANTY.
+ */
+
+declare(strict_types=1);
+
+namespace Maatify\Common\DTO;
+
+/**
+ * 🧩 **Class ConnectionConfigDTO**
+ *
+ * 🎯 **Purpose:**
+ * Represents a standardized, immutable configuration Data Transfer Object (DTO)
+ * for defining connection settings across supported adapters (MySQL, MongoDB, Redis, etc.).
+ *
+ * 🧠 **Key Features:**
+ * - Provides a unified structure for DSN-based connection setup.
+ * - Used for dependency injection and adapter factory initialization.
+ * - Immutable (`readonly`) to ensure safe configuration integrity at runtime.
+ *
+ * ✅ **Example Usage:**
+ * ```php
+ * use Maatify\Common\DTO\ConnectionConfigDTO;
+ *
+ * $config = new ConnectionConfigDTO(
+ *     dsn: 'mysql:host=127.0.0.1;dbname=maatify',
+ *     user: 'root',
+ *     pass: 'secret',
+ *     options: [
+ *         PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
+ *     ],
+ *     driver: 'pdo',
+ *     profile: 'production'
+ * );
+ * ```
+ */
+final readonly class ConnectionConfigDTO
+{
+    /**
+     * 🧠 **Constructor**
+     *
+     * Defines the full connection configuration parameters.
+     *
+     * @param string      $dsn      Data Source Name string (e.g., `"mysql:host=127.0.0.1;dbname=test"`).
+     * @param string|null $user     Optional database username (if applicable).
+     * @param string|null $pass     Optional database password (if applicable).
+     * @param array       $options  Optional adapter or driver-specific options.
+     * @param string|null $driver   Optional driver identifier (e.g., `"pdo"`, `"dbal"`, `"mysqli"`).
+     * @param string|null $profile  Optional connection profile name (useful for multi-env setups).
+     */
+    public function __construct(
+        public string $dsn,
+        public ?string $user = null,
+        public ?string $pass = null,
+        public array $options = [],
+        public ?string $driver = null,
+        public ?string $profile = null,
+    ) {}
+}

src/DTO/ConnectionConfigDTO.php

@@ -0,0 +1,50 @@
+<?php
+/**
+ * @copyright   ©2025 Maatify.dev
+ * @Library     maatify/common
+ * @Project     maatify:common
+ * @author      Mohamed Abdulalim (megyptm) <mohamed@maatify.dev>
+ * @since       2025-11-13 16:18
+ * @see         https://www.maatify.dev Maatify.com
+ * @link        https://github.com/Maatify/common  view project on GitHub
+ * @note        Distributed in the hope that it will be useful - WITHOUT WARRANTY.
+ */
+
+declare(strict_types=1);
+
+namespace Maatify\Common\Enums;
+
+/**
+ * 🧩 **Enum ConnectionTypeEnum**
+ *
+ * 🎯 **Purpose:**
+ * Defines the supported connection types across the Maatify ecosystem.
+ * Used to standardize adapter selection and environment configuration references.
+ *
+ * 🧠 **Key Features:**
+ * - Ensures strict typing for connection type values.
+ * - Prevents magic strings in adapter logic.
+ * - Facilitates polymorphic adapter resolution and dependency injection.
+ *
+ * ✅ **Example Usage:**
+ * ```php
+ * use Maatify\Common\Enums\ConnectionTypeEnum;
+ *
+ * $type = ConnectionTypeEnum::REDIS;
+ *
+ * if ($type === ConnectionTypeEnum::MYSQL) {
+ *     echo "Connecting to MySQL...";
+ * }
+ * ```
+ */
+enum ConnectionTypeEnum: string
+{
+    /** 🔹 MySQL relational database connection type. */
+    case MYSQL = 'mysql';
+
+    /** 🔹 MongoDB NoSQL database connection type. */
+    case MONGO = 'mongo';
+
+    /** 🔹 Redis in-memory data store connection type. */
+    case REDIS = 'redis';
+}