Download the PHP package power-modules/persistence without Composer

Modular Persistence

A type-safe, multi-tenant persistence layer for PHP 8.4+ built on the Modular Framework. It provides a robust Repository pattern implementation with native support for Postgres schemas and strict type safety.

💡 Robust: Built for complex applications requiring strict data integrity, multi-tenancy, and clear separation of concerns.

✨ Why Modular Persistence?

• 🔒 Type-Safe Schemas: Define database schemas using PHP Enums
• 🏢 Multi-Tenancy Native: Built-in support for dynamic Postgres schemas (namespaces)
• 📦 Repository Pattern: Generic CRUD repositories with decoupled SQL generation
• 🔄 Explicit Hydration: Full control over object-relational mapping without magic
• 🛠️ Scaffolding: CLI commands to generate your entire persistence layer
• ⚡ Performance: Lightweight wrapper around PDO with optimized query generation

🚀 Installation

⚙️ Configuration

Register the module in your ModularAppBuilder and provide configuration in config/modular_persistence.php:

🏗️ Quick Start

1. Define Schema

2. Implement persistence layer: entity, hydrator and repository

Note: You can generate these classes via the CLI commands (persistence:make-entity, persistence:make-hydrator, persistence:make-repository)

3. Register persistence layer in a module

📦 Repository API

AbstractGenericRepository implements the IRepository<TModel> interface, providing a complete CRUD contract out of the box. Type-hint IRepository<TModel> in consumers (services, controllers) — not AbstractGenericRepository — to enable decorator patterns (e.g., caching repos) and testability:

All repository methods:

🔍 Conditions

Type-safe query conditions using schema enum cases:

JSONB Conditions

PostgreSQL JSONB operators are supported natively:

Raw SQL Conditions

For complex expressions that cannot be represented via Condition (e.g. custom casts, functions, or advanced JSONB paths), use addRawCondition() on any statement:

addRawCondition() is available on SelectStatement, UpdateStatement, and DeleteStatement. Raw conditions are AND-joined with standard conditions. Bind::json() auto-encodes arrays to JSON strings. bash php bin/console persistence:generate-schema App\Schema\UserSchema bash

Start PostgreSQL (port 15432)

make docker-up

Run all tests (unit + integration)

make test

Run unit tests only (no DB required)

make test-unit

Run integration tests only (requires PostgreSQL)

make test-integration

Static analysis (PHPStan level 8)

make phpstan

Code style check

make codestyle

Stop PostgreSQL

make docker-down

### Test Architecture

- **Unit tests** (`tests/Unit/`): Fast, no database — mock `IDatabase`/`IQueryExecutor` to verify SQL generation and bind parameters
- **Integration tests** (`tests/Integration/`): Run against a real PostgreSQL 17 instance, testing the full stack from repository through PDO
- **Test isolation**: Integration tests use transaction-based isolation (`BEGIN` in setUp / `ROLLBACK` in tearDown) for speed. Tests that exercise transactions or DDL manage their own cleanup.
- **Fixtures**: Shared test entities, schemas, hydrators, and repositories live in `tests/Unit/Fixture/` (mocked DB) and `tests/Integration/Fixture/` (real DB). Integration support classes (`PostgresTestCase`, `ConnectionHelper`) live in `tests/Integration/Support/`.
- **Namespace**: `Modular\Persistence\Test\` (PSR-4 → `tests/`)

### CI

The GitHub Actions workflow automatically provisions a PostgreSQL service container and runs the full suite on every push/PR.