Technical Evaluation

Polyglot Persistence Fit: The package enables seamless integration of MongoDB (ODM) alongside existing Doctrine ORM (SQL) entities in an API Platform application, aligning with a polyglot persistence architecture. This is valuable for:
- Storing unstructured/semi-structured data (e.g., JSON documents, nested arrays) in MongoDB while keeping relational data in SQL.
- Leveraging API Platform’s core features (hydration, serialization, validation) for both SQL and NoSQL entities.
- Use cases like content management (CMS), analytics, or real-time data where MongoDB’s flexibility excels.
API Platform Compatibility: Since API Platform is built on Symfony, this package integrates natively with its resource system, state processors, and serialization groups, reducing boilerplate for MongoDB-backed APIs.
Schema Flexibility: MongoDB’s schema-less nature contrasts with Doctrine ORM’s rigid schema, which may require careful design to avoid data consistency or query performance trade-offs.

Low-Coupling Design: The package extends Doctrine ODM (MongoDB) to work with API Platform’s resource system, meaning:
- Existing controllers, filters, and state processors can be reused with minimal changes.
- Hydration/denormalization works out-of-the-box for MongoDB entities.
- Validation (via Symfony Validator) applies uniformly across SQL/NoSQL.
Dependency Overlap:
- Requires Doctrine MongoDB ODM (doctrine/mongodb-odm) as a dependency, adding ~50MB to the footprint.
- API Platform core (api-platform/core) must already be in use (not a standalone solution).
ORM/ODM Duality Challenges:
- Repository Patterns: API Platform’s ApiPlatform\Doctrine\Orm\Filter\* filters won’t work with ODM; custom filters may be needed.
- Query Building: MongoDB’s query language (e.g., $lookup, aggregation pipelines) differs from DQL, requiring custom DTOs or GraphQL-like queries for complex joins.
- Transactions: MongoDB lacks ACID transactions across collections (unlike SQL), which may complicate business logic spanning both databases.

Risk Area	Severity	Mitigation Strategy
Data Consistency	High	Implement event sourcing or saga pattern for cross-database transactions. Use MongoDB change streams + Symfony Messenger for sync.
Query Performance	Medium	Avoid complex joins; use denormalized data or application-side joins. Profile with `explain()` in MongoDB.
Schema Migration	Medium	Use Doctrine Migrations for SQL and custom scripts for MongoDB (no native migration tool).
Tooling Gaps	Low	Leverage API Platform’s CLI for SQL schema; use MongoDB Compass or NoSQL tools for ODM.
Learning Curve	Medium	Document query differences (e.g., `find()` vs. `createQueryBuilder()`) and serialization quirks (e.g., `@Groups` vs. MongoDB’s dynamic schema).

Why MongoDB?
- Is this for scale (horizontal sharding), flexibility (schema evolution), or specific features (geospatial, full-text search)?
- Could PostgreSQL JSONB or Elasticsearch achieve similar goals with lower operational overhead?
Data Model Design
- How will relationships between SQL (e.g., User in PostgreSQL) and NoSQL (e.g., UserProfile in MongoDB) be managed?
- Will embedded documents or references be used, and how will this affect API responses?
Query Complexity
- Are there multi-collection queries (e.g., joins) that would require application-side logic or custom DTOs?
- Will GraphQL or custom query parameters be needed to bridge SQL/NoSQL query differences?
Performance SLAs
- What are the read/write latency requirements for MongoDB vs. SQL?
- How will caching (e.g., API Platform’s cache:clear) be handled for hybrid data?
Team Expertise
- Does the team have MongoDB/Doctrine ODM experience, or will this require upskilling?
- Are there existing tools (e.g., MongoDB Atlas, Compass) that will be adopted?

Integration Approach

Core Stack Compatibility:
- API Platform (Symfony-based) + Doctrine ODM = Native integration with minimal friction.
- Works alongside Doctrine ORM, Elasticsearch, or other API Platform data providers.
Recommended Stack Additions:
- Symfony Messenger: For event-driven sync between SQL/NoSQL.
- MongoDB Atlas: For managed operations (backups, scaling).
- API Platform Admin: For unified API documentation (Swagger/OpenAPI) across SQL/NoSQL resources.
Avoid If:
- The team lacks MongoDB expertise and the use case doesn’t justify its complexity.
- Strong consistency across SQL/NoSQL is critical (e.g., financial systems).

Phase 1: Proof of Concept (2-4 weeks)
- Add api-platform/doctrine-odm and doctrine/mongodb-odm to composer.json.
- Create a single MongoDB entity (e.g., ProductVariant) and expose it via API Platform.
- Test CRUD operations, serialization, and validation.
- Compare performance with SQL equivalent.
Phase 2: Hybrid Data Model (4-8 weeks)
- Design relationships between SQL (e.g., Product) and MongoDB (e.g., ProductVariant).
- Implement custom filters or DTOs for complex queries.
- Set up event listeners (e.g., postPersist) to sync data if needed.
Phase 3: Full Integration (8+ weeks)
- Migrate legacy MongoDB collections (if any) to the new ODM structure.
- Implement caching strategies (e.g., StashDriver for API Platform).
- Add monitoring (e.g., MongoDB slow query logs, API Platform metrics).

Component	Compatibility Notes
API Platform Core	✅ Full support (resources, serialization, validation).
Doctrine ORM	⚠️ No direct integration; treat as separate data sources.
Symfony Validator	✅ Works for MongoDB entities (same as ORM).
Doctrine Migrations	❌ No native support; use custom scripts or MongoDB Migration Tool.
API Platform Filters	❌ ORM-specific filters won’t work; use custom filters or GraphQL.
Cache (APCu, Redis)	✅ Works, but cache invalidation must account for both SQL/NoSQL changes.

Start with Non-Critical Data
- Migrate read-heavy, flexible-schema data (e.g., logs, user preferences) first.
Leverage Existing APIs
- Reuse API Platform’s ApiResource annotations; no need to rewrite controllers.
Gradual Query Replacement
- Replace complex SQL queries with MongoDB equivalents incrementally.
Last: Cross-Database Logic
- Implement sagas or event sourcing only after core APIs are stable.

Dependency Management:
- Doctrine ODM requires MongoDB driver (ext-mongodb) and PHP extensions (e.g., php-mongodb).
- Versioning: ODM and API Platform must stay in sync (check compatibility matrix).
Schema Evolution:
- MongoDB: Schema changes are manual (no migrations); use feature flags for backward compatibility.
- SQL: Continue using Doctrine Migrations.
Tooling:
- MongoDB Compass for ad-hoc queries.
- API Platform’s make:entity won’t work for ODM; use custom commands or **ODM’s php app/console doctrine:mongoDB:schema:update).

Debugging Complexity:
- Stack traces may involve two databases; log context switches (