Maatify Data Repository

Unified repository abstraction layer normalizing MySQL, MongoDB, and Redis real & fake drivers.

---

🚀 Overview

Maatify Data Repository separates domain logic from database-specific implementations and provides a unified API supporting:

• Real Drivers (maatify/data-adapters)
• Fake Drivers (maatify/data-fakes)

Why this library?

• Zero driver lock-in
• Deterministic testing without Docker
• Static analysis with PHPStan Level Max
• Unified CRUD/Filters/Pagination across MySQL, MongoDB, and Redis

Supported Drivers

Type	Real Drivers	Fake Drivers
MySQL	PDO / Doctrine DBAL	In-memory SQL-like tables
MongoDB	mongodb/mongodb	In-memory BSON-like collections
Redis	redis / predis	In-memory key-value store

---

📦 Installation

composer require maatify/data-repository

---

⚡ Quick Usage

1) Create a Repository

use Maatify\DataRepository\Base\BaseMySQLRepository;

/** @extends BaseMySQLRepository<array> */
class UserRepository extends BaseMySQLRepository
{
    protected string $tableName = 'users';
}

2) Use in Production (Real Adapter)

$resolver = new DatabaseResolver(new EnvironmentConfig(__DIR__));
$adapter  = $resolver->resolve('mysql.main');

$repo = new UserRepository($adapter);
$users = $repo->findBy(['active' => 1]);

3) Use in Testing (Fake Adapter)

$storage = new FakeStorageLayer();
$adapter = new FakeMySQLAdapter($storage);

$storage->seed('users', [
    ['id' => 1, 'active' => 1, 'name' => 'Alice'],
]);

$repo = new UserRepository($adapter);
$repo->findBy(['active' => 1]); // Alice

---

💎 Hydration & DTOs

class UserDto {
    public int $id;
    public string $name;
}

/** @extends BaseHydrator<UserDto> */
class UserHydrator extends BaseHydrator {}

$repo->setHydrator(new UserHydrator());
$user = $repo->findObject(1);

---

🧩 Key Features

• Generic CRUD: find, findBy, findOneBy, insert, update, delete, count, paginate.
• Advanced Filtering: IN, LIKE, ranges (>, <), IS NULL.
• Sorting: Multi-column orderBy normalized across drivers.
• Pagination: Standardized paginate() with PaginationResultDTO.
• Hydration: Transform arrays to DTOs via HydratorInterface.
• Strict Validation: Prevents invalid offsets, limits, or types.
• Static Analysis: Fully Generic-aware (@template T) for PHPStan Level Max.

---

📄 Documentation

• New Developer Onboarding
• Full Documentation
• Practical Usage Guide (Examples)

📚 Development History & Phase Details

The development of this library follows a strict phase-based roadmap.

• Phase 1: Bootstrap
• Phase 3: Generic CRUD
• Phase 15: Pagination
• Phase 16: Pagination Optimization
• Phase 17: Hydrated Pagination
• Phase 20: SQL & Filter Improvements
• Phase 21: Architecture Decoupling
• Phase 22: FilterParser Extraction
• Phase 26: Public API Tightening
• Phase 28: PHPStan Generics
• Phase 29: Developer Experience

---

📚 Development History & Phase Details

Click to expand

This library evolves through a strict phase-based roadmap.

Major Completed Phases

• Phase 1 – Bootstrap & Foundation
• Phase 3 – Generic CRUD
• Phase 15–17 – Pagination Improvements & Hydration
• Phase 20 – SQL & Filter Enhancements
• Phase 21 – Architecture Decoupling
• Phase 22 – FilterParser Extraction
• Phase 26 – Public API Tightening
• Phase 28 – PHPStan Generics
• Phase 29 – Developer Experience

Full details available in docs/phases/.

---

🧱 Dependencies Overview

maatify/data-repository relies on Maatify core ecosystem + selected open-source libraries.

---

🧩 Maatify Ecosystem Dependencies

Package	Description	Role
maatify/bootstrap	Environment loader, diagnostics, helpers	Powers .env and adapter bootstrapping
maatify/data-adapters	Real MySQL/Mongo/Redis adapters	Production database connectivity
maatify/data-fakes	Fake in-memory drivers	Deterministic, Docker-free testing

---

🔌 Direct Open-Source Dependencies

Library	Purpose
psr/log	Logging interface
phpunit/phpunit	Test suite
phpstan/phpstan	Static analysis
mongodb/mongodb	MongoDB driver
predis/predis / php-redis	Redis driver
doctrine/dbal (optional)	MySQL DBAL abstraction

---

🔄 Indirect Dependencies (via bootstrap)

Library	Purpose
vlucas/phpdotenv	.env loader
psr/container	DI compatibility

Special thanks to the maintainers of these open-source libraries for providing the stable foundations that make this project possible. ❤️

---

🧪 Testing

composer test

Runs:

• Real vs Fake consistency checks
• Filter/Order parser tests
• Pagination & Hydration tests
• Architecture tests
• Coverage with Clover output

---

🪪 License

MIT License
© Maatify.dev — Free to use, modify, and distribute with attribution.

---

👤 Author

Engineered by Mohamed Abdulalim (@megyptm)
Backend Lead & Technical Architect — https://www.maatify.dev

---

🤝 Contributors

Special thanks to the Maatify.dev engineering team and all open-source contributors.
Your efforts help make this repository stronger and more reliable.

Contributions are always welcome!
Before opening a Pull Request, please make sure to read our
Contributing Guide and Code of Conduct.

---

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