Download the PHP package kabiroman/adaptive-entity-manager without Composer

Adaptive Entity Manager

A flexible PHP package implementing the Doctrine ObjectManager interface for seamlessly managing entities across different data sources: SQL databases, REST APIs, GraphQL endpoints, etc., using pluggable adapters.

Overview

Adaptive Entity Manager (AEM) is a powerful entity management system that provides a unified interface for working with entities across multiple data sources. It implements Doctrine's ObjectManager interface while offering enhanced flexibility through its adapter-based architecture.

AEM is particularly useful when you rely on Doctrine DBAL (or similar) for connections and SQL/query building, but adopting full Doctrine ORM entity mapping is impractical—for example, when integrating several external or legacy databases with uneven schemas.

In hexagonal (ports and adapters) architectures, place AEM in the infrastructure adapters behind your application or domain repositories so persistence concerns do not leak into the core model.

Documentation: docs/README.md (guides for Doctrine, DDD, hexagonal architecture, and legacy migration).

Features

• Pluggable data source adapters
• Unified entity management interface
• Support for multiple data sources simultaneously
• Value Objects support: Built-in support for immutable Value Objects with automatic conversion
• Transaction management
• Lazy loading through proxy objects
• Flexible entity repository system
• Comprehensive metadata management
• Efficient unit of work implementation

Recent Updates (v1.6.0)

Domain value objects (metadata) and VO-aware manager API

• Map value_object fields to domain types without ValueObjectInterface via metadata: class (preferred) or valueObjectClass, from (static factory), to (serialization). Details: docs/VALUE_OBJECTS.md.
• ValueObjectAwareEntityManagerInterface carries getValueObjectRegistry() / hasValueObjectSupport(); the base EntityManagerInterface no longer declares them — typehint the extended interface when you rely on VO registry helpers.
• loadAll criteria apply the same object→storage rules as flush for value_object fields; the instance must match the property’s declared VO class.
• Stricter config: conflicting class and valueObjectClass are rejected; conversion checks the property type before calling metadata to.
• Example: examples/ddd_domain_vo_demo.php (dev autoload Examples\Ddd\).
• Process-wide caveat: one shared static entity factory per PHP process — several EntityManager instances with different VO/metadata setups are not fully isolated (CHANGELOG for v1.6.0, Known limitations).

Earlier in v1.5.0 — Quality, CI, and tooling

• CI matrix for PHP 8.1, 8.2, 8.3, and 8.4 and a CI status badge in this README.
• PHPStan at level 5 with the PHPUnit extension, a baseline quality gate, and composer analyse / composer check scripts.
• Targeted tests added for flush rollback on insert failure, commit event order, preFlush lifecycle, flush with default optimized metadata, loadAll criteria (field-to-column and boolean source values), PersistentCollection lazy init, and EntityManager proxy helpers.
• English documentation roadmap / RFC updates in the repo.

Earlier in v1.5.0 — API and documentation

• Nullable parameters made explicit where needed for PHP 8.4 readiness.
• Positioning refreshed around Doctrine DBAL, legacy databases, and hexagonal architectures.

Earlier in v1.4.0 — Boolean value mapping

• values option for boolean fields maps non-standard source flags (Y/N, 0/1, T/F) to PHP bool; bidirectional hydration and persistence, plus criteria mapping before adapter queries.
• ClassMetadata::getFieldOption() for reading arbitrary field options from metadata.
• If values is omitted, behavior is unchanged.

Requirements

• PHP 8.1 or higher (Composer platform requirement)
• CI tests this package on PHP 8.1, 8.2, 8.3, and 8.4 (see .github/workflows/ci.yml), including PHPStan at level 5 (composer analyse) on each matrix version
• Composer for dependency management

Installation

Install the package via Composer:

Dependencies

• doctrine/persistence: ^3.0 || ^4.0
• laminas/laminas-code: ^4.0
• psr/container: ^1.1 || ^2.0
• symfony/cache: ^6.0 || ^7.0
• symfony/string: ^6.0 || ^7.0

Basic Usage

Key Components

Entity Manager

The core component that manages entity operations:

Repositories

Custom repositories for entity-specific operations:

Unit of Work

Tracks entity states and manages transactions:

Advanced Features

ValueObject Support

Adaptive Entity Manager provides built-in support for immutable Value Objects, allowing you to work with domain-specific types instead of primitive values.

Built-in ValueObjects

• Email: Email validation with domain/local part extraction
• Money: Currency-aware monetary values with arithmetic operations
• UserId: Type-safe user identifiers with validation

Basic Usage

Entity Configuration

Configure your entity metadata to use ValueObjects:

Custom ValueObjects

Create your own ValueObjects by implementing ValueObjectInterface:

For complete ValueObject documentation, see docs/VALUE_OBJECTS.md.

Custom Data Adapters

Create custom adapters for different data sources by implementing the appropriate interfaces in the DataAdapter namespace.

Event System

The Adaptive Entity Manager provides a flexible event system based on PSR-14, allowing you to hook into various stages of the entity lifecycle. This enables powerful extensibility and modularity, letting you execute custom logic before or after core entity operations.

Key Events:

• PrePersistEvent: Dispatched before an entity is persisted.
• PostPersistEvent: Dispatched after an entity has been persisted.
• PreUpdateEvent: Dispatched before an entity is updated.
• PostUpdateEvent: Dispatched after an entity has been updated.
• PreRemoveEvent: Dispatched before an entity is removed.
• PostRemoveEvent: Dispatched after an entity has been removed.

Usage Example (Conceptual):

To listen to events, you would implement a PSR-14 compatible event listener. For example, using a simple event dispatcher (or your framework's own, like Symfony's EventDispatcher):

Data Adapter Example

The Adaptive Entity Manager allows you to create custom data adapters for different data sources. Here's a simple example of implementing a REST API data adapter for a User entity.

Basic Implementation

Usage Example

Here's how to use the custom data adapter with the Adaptive Entity Manager:

Key Features

• REST API Integration: Simple implementation for RESTful APIs
• Automatic Case Conversion: Handles conversion between snake_case (API) and camelCase (entities)
• CRUD Operations: Complete set of Create, Read, Update, and Delete operations
• Query Support: Built-in support for filtering, sorting, and pagination
• Clean Implementation: Extends AbstractDataAdapter for common functionality

Available Methods

Helper Methods

The AbstractDataAdapter provides useful case conversion methods:

• toCamelCaseParams(): Converts array keys to camelCase
• toSnakeCaseParams(): Converts array keys to snake_case

Tips

1. Always handle data transformation between your storage format and entity format
2. Implement proper error handling for API responses
3. Use type hints and return types for better code reliability
4. Consider implementing caching for frequently accessed data
5. Follow RESTful conventions for API endpoints

Next Steps

• Implement custom query builders for complex filtering
• Add caching layer for better performance
• Implement batch operations for multiple entities
• Add logging for debugging purposes
• Implement retry mechanisms for failed API calls

Metadata Management

Comprehensive metadata handling for entity mapping and relationship management.

Metadata example

This metadata configuration provides:

• Clear mapping between database columns and entity properties
• Relationship management (One-to-One, One-to-Many)
• Automatic lifecycle event handling
• Type safety through explicit type definitions
• Flexible data adapter integration

Boolean value mapping

If your data source uses flags like Y|N, 0|1, or T|F, you can normalize them to PHP bool using the values option on a field with type => 'boolean' in your metadata:

Notes:

• Keys in values are matched case-insensitively for strings; exact match takes precedence.
• If values is not specified, the source value is used as-is (no implicit Y/N handling).
• Repository criteria on boolean fields also honor values when querying: passing ['isActive' => true] will be converted to the corresponding source value (e.g., 'Y'). Arrays in criteria (e.g., ['isActive' => [true, false]]) are mapped element-wise.
• During persistence (object → row), boolean properties are converted to the configured source representation using values (e.g., true → 'Y').

User entity class that this metadata would describe:

Entity Proxies

The system supports lazy loading through proxy objects, automatically generating proxy classes when needed.

Value Objects

The Adaptive Entity Manager provides powerful Value Object support for better domain modeling and type safety. Value Objects are immutable objects that are defined by their values rather than identity.

For detailed documentation on Value Objects, see docs/VALUE_OBJECTS.md.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This package is open-sourced software licensed under the MIT license.

Author

• Ruslan Kabirov - [email protected]

Support

For issues, questions, or contributions, please use the GitHub issue tracker.