Disable Orm Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Schema Evolution Strategy: The bundle excels at enabling zero-downtime schema changes by decoupling ORM visibility from database persistence. This directly supports strangler pattern or phased migration strategies where legacy and modern codebases coexist.
• Symfony Ecosystem Alignment: Designed for Doctrine ORM’s metadata-driven architecture, making it a natural fit for Symfony applications relying on Doctrine for persistence. The use of metadata factories is a well-established pattern in Doctrine, reducing integration friction.
• Limitation: One-way operation (disable-only) may require complementary tools (e.g., feature flags) for bidirectional schema toggling. Not suitable for dynamic field re-enabling or runtime toggling.

Integration Feasibility

• Doctrine Version Support: Explicitly supports Doctrine ORM 2.7+ and Symfony 5.4+, aligning with modern stacks. The 2026 release date suggests active maintenance, but the zero stars raise questions about adoption.
• Metadata Conflicts: Risk of collisions with other bundles modifying ORM metadata (e.g., StoDoctrineExtensionsBundle, Gedmo). Requires pre-integration audit of EntityManager configurations.
• Testing Complexity: Requires comprehensive integration tests to validate:
  • Query builders (DQL, Criteria).
  • Hydration (e.g., getProperty(), find()).
  • Raw SQL bypass paths (e.g., QueryBuilder::expr()).

Technical Risk

Key Questions

1. Schema Governance:
   • How are database schema changes currently approved/coordinated? Will this bundle replace existing migration gates?
2. Field Lifecycle:
   • Which fields are immediate candidates for exclusion? Are they truly deprecated or might they need reintroduction?
3. Query Safety:
   • Are there dynamic queries (e.g., user-provided fields in WHERE) that could break if fields are excluded?
4. Rollback Strategy:
   • How will we re-enable excluded fields if a critical bug is discovered (e.g., missing data access)?
5. Long-Term Maintenance:
   • Who will update @DisableORM annotations as new fields are deprecated? Will this become a technical debt sink?

Integration Approach

Stack Fit

• Ideal For:
  • Monolithic Symfony applications with multi-version deployments (e.g., blue-green, canary).
  • Teams using Doctrine ORM for persistence and needing gradual schema evolution.
• Not Ideal For:
  • Microservices: Each service manages its own schema; no shared ORM layer.
  • Non-Doctrine Persistence: (e.g., Eloquent, Propel, or raw SQL apps).
  • Greenfield Projects: Overkill unless anticipating legacy system integration.

Migration Path

1. Preparation Phase:
   • Audit Entities: Identify fields marked for future removal (e.g., via @deprecated tags or legacy feature flags).
   • Query Analysis: Use tools like Doctrine Profiler or Xdebug to find queries relying on excluded fields.
2. Bundle Installation:

   composer require dualmedia/disable-orm-bundle --dev
   

   • Register in config/bundles.php:

     DualMedia\DisableORMBundle\DisableORMBundle::class => ['all' => true],
     

3. Configuration:
   • Override metadata_factory_name in config/packages/doctrine.yaml:

     doctrine:
         orm:
             entity_managers:
                 default:
                     metadata_factory_name: DualMedia\DisableORMBundle\Metadata\Factory\DisableORMMetadataFactory
     

   • Add @DisableORM to target fields (PHP 8+ attributes or YAML annotations).
4. Validation:
   • Run schema validation:

     php bin/console doctrine:schema:validate
     

   • Test critical workflows with excluded fields:
     • Entity hydration ($entity->getField()).
     • Query builders ($qb->select('e.field')).
     • Raw SQL queries (must explicitly reference excluded fields).

Compatibility

• Doctrine Extensions:
  • Test with StoDoctrineExtensionsBundle, Gedmo, or API Platform for conflicts.
  • Example conflict: Gedmo’s Timestampable might fail if updatedAt is excluded.
• Custom Repositories:
  • Ensure findBy()/findOneBy() methods don’t assume excluded fields exist.
• Third-Party Libraries:
  • EasyAdmin, SonataAdmin, or API Platform may rely on ORM metadata. Review their Doctrine integration docs.

Sequencing

1. Pilot Phase:
   • Start with low-risk entities (e.g., audit logs, deprecated features).
   • Example: Exclude legacyUserId from UserEntity if migrated to OAuth.
2. Gradual Rollout:
   • Exclude fields in new code branches before merging to main.
   • Use feature flags to gate excluded-field access in legacy code.
3. Automation:
   • Add PHPStan/Psalm rules to detect @DisableORM misuse:

     includes:
         - vendor/dualmedia/disable-orm-bundle/extension.neon
     

   • Implement CI checks (e.g., fail if getExcludedField() is called).
4. Deprecation:
   • Mark excluded fields with @deprecated in code.
   • Remove fields from database schema in a separate migration after full rollout.

Operational Impact

Maintenance

• Configuration Management:
  • Risk: @DisableORM annotations may become stale if not updated alongside field deprecations.
  • Mitigation:
    • Use pre-commit hooks to scan for unused annotations.
    • Document ownership of deprecated fields (e.g., "Team X owns legacyField until Q3 2024").
• Debugging Overhead:
  • Risk: Excluded fields may cause silent failures (e.g., PropertyAccessException).
  • Mitigation:
    • Log warnings when excluded fields are accessed via reflection.
    • Add runtime checks in EntityListeners.

Support

• Developer Onboarding:
  • Training Needed:
    • How to safely exclude fields (e.g., avoid WHERE clauses).
    • How to debug queries when fields disappear.
  • Documentation:
    • Runbook for "Why is my query returning fewer columns?".
    • Example: "If SELECT * fails, explicitly list fields in QueryBuilder."
• Legacy Code Paths:
  • Expectation: Teams using raw SQL or dynamic property access will need updates.
  • Example: Replace $entity->$field with $entity->{'field'} if field is excluded.

Scaling

• Performance:
  • Metadata Factory Overhead: Minimal for most apps, but benchmark if using >10,000 entities.
  • Query Planning: Excluded fields may affect index usage or join optimizations.
    • Example: JOIN e.legacyField will fail if legacyField is excluded.
• Database Impact:
  • No schema changes, but raw SQL must explicitly reference excluded fields.
  • Migration Strategy: Remove excluded fields from schema only after all legacy versions are deprecated.

Failure Modes

Ramp-Up

• **Team Read