README

Maatify Data Adapters

Clean, DI-first infrastructure adapters for real drivers.

maatify/data-adapters provides explicit adapter implementations around real infrastructure drivers such as PDO, Redis, and MongoDB.

It exists to act as a dependency-injection boundary — nothing more.

What This Package IS

• A DI boundary around infrastructure drivers
• An ownership wrapper for real driver instances
• Explicit by design (no magic, no auto-detection)
• Deterministic and statically analyzable
• 100% testable without real databases

➡️ See full scope definition:
docs/01-scope.md

What This Package IS NOT

This package is NOT:

• ❌ A unified database API
• ❌ An abstraction layer
• ❌ An ORM or query builder
• ❌ A repository layer
• ❌ A connection manager
• ❌ A configuration loader
• ❌ A lifecycle or retry system

If you expect convenience or API unification, do not use this package.

Supported Drivers

MySQL

• PDO
• Doctrine DBAL (Connection)

Redis

• ext-redis
• Predis\Client

MongoDB

• MongoDB\Database

Driver choice is explicit and decided by the application or DI container.

Core Mental Model

Application
   ↓
Configuration / Secrets / Env   (outside this package)
   ↓
Real Driver (PDO / Redis / Mongo)
   ↓
Adapter (DI boundary only)
   ↓
Application / Higher Layers

• No env access
• No runtime detection
• No hidden behavior

Adapter Contract

All adapters implement a minimal contract:

interface AdapterInterface
{
    public function getDriver(): object;
}

• Runtime return type is object
• Static typing is preserved via docblock generics
• No unified API is introduced

➡️ Static analysis details: docs/03-static-analysis.md

Available Adapters

• MySQLPDOAdapter
• MySQLDBALAdapter
• RedisAdapter (ext-redis)
• RedisPredisAdapter
• MongoDatabaseAdapter

Each adapter:

• Accepts a ready driver instance
• Stores it
• Returns it via getDriver()

Nothing else.

Factories (Optional Convenience)

Factories exist only to reduce boilerplate.

• No env reading
• No auto-detection
• No hidden defaults
• Typed error boundary via AdapterCreationException

Factories are optional and not required for normal usage.

➡️ See: docs/06-factories.md

Usage Philosophy

This package enforces:

• Explicit DI
• Explicit configuration
• Explicit error handling
• Explicit responsibility boundaries

It intentionally avoids:

• Full examples
• Framework-specific helpers
• Runtime convenience

Common Misuse Warnings

• ❌ Serializing adapters or drivers
• ❌ Expecting unified behavior
• ❌ Treating adapters as services

➡️ Detailed warnings: docs/04-misuse-traps.md

When to Use This Package

Use it if you want:

• Predictable infrastructure boundaries
• Explicit DI
• Full control over drivers

When NOT to Use This Package

Do NOT use it if you want:

• Automatic configuration
• API unification
• Runtime magic

Documentation Index

• Scope & Boundaries
• Design Decisions
• Static Analysis
• Misuse Traps
• Lifecycle
• Factories
• Dependency Policy & Matrix

Examples

The following examples demonstrate explicit, real-world usage of maatify/data-adapters with supported drivers.

These examples are intentionally minimal:

• No frameworks
• No helpers
• No bootstrap logic
• Explicit driver creation and adapter usage

MySQL

• PDO Example
• Doctrine DBAL Example

Redis

• ext-redis Example
• Predis Example

MongoDB

• MongoDB Database Example

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

Contributions are welcome. Please read the Contributing Guide before opening a PR.

_{Built with ❤️ by Maatify.dev — Infrastructure-first PHP libraries}