README

Unified Repository Abstraction Layer for the Maatify Ecosystem

🧩 Overview

maatify/data-repository provides a clean, unified repository abstraction layer above maatify/data-adapters.

It standardizes how all MySQL, MongoDB, and Redis operations are performed throughout the Maatify ecosystem by enforcing:

• Repository-first data interaction
• DTO-friendly hydration workflow
• Consistent error handling
• Shared abstraction for all business modules
• Zero direct PDO/Mongo/Redis driver usage

This ensures clean architecture, high testability, and full adapter isolation.

🚀 Features

✅ Unified Repository Base Classes

• BaseMySQLRepository
• BaseMongoRepository
• BaseRedisRepository
• Shared BaseRepository

✅ Repository Interfaces

• RepositoryInterface
• MySQL / Mongo / Redis specific contracts

✅ DTO Hydration Layer (Phase 4)

• Simple hydration pipeline
• Type-safe mapping

✅ Flexible Database Profiles

Works seamlessly with:

mysql.main
mysql.reporting
mongo.logs
redis.cache

🔮 Future Enhancements

• Repository caching (v1.1.0)
• Observers (v1.2.0)
• Unit of Work (v2.0.0)
• Query Builder integration

📥 Installation

composer require maatify/data-repository

Autoloads into:

Maatify\DataRepository\

🏗️ Architecture

src/
  Contracts/
    RepositoryInterface.php
    MySQLRepositoryInterface.php
    MongoRepositoryInterface.php
    RedisRepositoryInterface.php

  Exceptions/
    RepositoryException.php
    NotFoundException.php
    InvalidRepositoryArgumentException.php
    UnsupportedDriverException.php

  Repository/
    BaseRepository.php
    BaseMySQLRepository.php
    BaseMongoRepository.php
    BaseRedisRepository.php   ← Added in Phase 2

✔ Clean separation ✔ PSR-12 compliant ✔ No circular dependencies ✔ No business logic inside repositories

🧠 Usage Examples (After Phase 2)

MySQL Example

$user = $this->userRepository->find(['active' => 1]);

Redis Example

$this->cacheRepository->set('session:123', ['id' => 123], ttl: 3600);

Mongo Example

$logs = $this->auditRepository->find(['level' => 'warning']);

🔧 Composer Scripts

composer test      # PHPUnit
composer analyse   # PHPStan
composer format    # php-cs-fixer

🧪 Testing

PHPUnit includes:

• phpunit.xml
• SmokeTest (Phase 1)
• Full Base Repository Test Suite (Phase 2)
• GitHub Actions integration

Run tests:

composer test

📝 Changelog

See CHANGELOG.md Semantic Versioning (SemVer).

🗺️ Roadmap

v1.0.0

✔ Phase 1 — Bootstrapping

• Namespace & structure
• Contracts
• Exceptions
• PHPUnit
• CI pipeline
• Initial docs

✔ Phase 2 — Base Repository Layer (Completed)

• Base MySQL/Mongo/Redis repositories
• DatabaseResolver integration
• Dynamic profile support
• Fully typed & PHPStan-clean
• Comprehensive PHPUnit coverage

⏳ Phase 3 — Generic Repositories

⏳ Phase 4 — DTO Hydration Layer

⏳ Release v1.0.0

v1.1.0

• Repository Caching Layer

v1.2.0

• Repository Observers (before/after save)

v2.0.0

• Unit Of Work
• Entity Tracking
• Transaction Boundaries

🤝 Contributing

See CONTRIBUTING.md

• PSR-12
• Strict typing
• Mandatory PHPUnit tests
• No direct driver usage

🔐 Security

See SECURITY.md

Report vulnerabilities privately at: 📧 security@maatify.dev

📜 Code of Conduct

See CODE_OF_CONDUCT.md

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

👤 Author

Mohamed Abdulalim — Backend Lead & Technical Architect
🔗 https://www.maatify.dev | ✉️ mohamed@maatify.dev

🤝 Contributors

Special thanks to the Maatify.dev engineering team and open-source contributors.

_{Built with ❤️ by Maatify.dev — Unified Ecosystem for Modern PHP Libraries}