README

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

📚 Development History & Phase Details

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

📚 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

👤 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}

maatify / data-repository

Maintainers

Details