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

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

🛑 MongoDB ObjectId Casting Rules

Important: To ensure predictability, this library enforces strict rules for MongoDB ID casting.

• Casting is allowed ONLY in find(id)
• 24-char hex strings are cast ONLY in find(id)
• findBy, paginate, and filters NEVER cast automatically
• Explicit new ObjectId(...) is required in filters

Positive Example (Casting happens):

// Automatically converts string "507f1f77bcf86cd799439011" to ObjectId
$repo->find("507f1f77bcf86cd799439011");

Negative Example (No casting happens):

// Remains a literal string "507f1f77bcf86cd799439011"
$repo->findBy(['custom_id' => "507f1f77bcf86cd799439011"]);

📄 Documentation

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

📚 Development History & Phase Details

🧱 Dependencies Overview

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

🧩 Maatify Ecosystem Dependencies

🔌 Direct Open-Source Dependencies

🔄 Indirect Dependencies (via bootstrap)

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}