Object Reference Bundle Laravel Package

Product Decisions This Supports

• Polymorphic Relationships Without Complex Joins: Enables storing references to multiple entity types (e.g., Actor, Director, Producer) in a single column via closures, simplifying schema design for polymorphic associations. Avoids the need for discriminator columns or complex SingleTableInheritance/ClassTableInheritance setups.
• Roadmap for "Soft Polymorphism": Justifies building a lightweight, flexible alternative to Doctrine’s native polymorphic associations (e.g., ManyToOne with targetEntity dynamic loading) when performance or simplicity is prioritized over strict ORM conventions.
• Build vs. Buy: Buy for teams already using Laravel/Symfony with Doctrine ORM who need a quick, low-overhead solution for polymorphic references. Build only if requiring deep customization (e.g., caching, bulk operations) or integrating with non-Doctrine systems.
• Use Cases:
  • Content Management: Storing "authored by" relationships where the author can be a User, Organization, or AIModel.
  • Audit Trails: Tracking actions tied to polymorphic entities (e.g., createdBy could be a User or ServiceAccount).
  • Legacy Migration: Gradually replacing raw JSON columns storing entity IDs/types with typed references.

When to Consider This Package

• Adopt When:

  • Your team uses Symfony/Laravel with Doctrine ORM and needs polymorphic references without bloating the database with discriminator columns.
  • You prioritize simplicity over strict ORM compliance (e.g., avoiding SingleTableInheritance or ClassTableInheritance).
  • The referenced entities are frequently loaded individually (not in bulk), as this package uses lazy-loading closures.
  • You’re okay with manual ID/type field management (the package requires actorId and actorType fields to be declared, even if unused).

• Look Elsewhere When:

  • You need bulk operations (e.g., querying all Story entities with their Actor loaded in one query). This package’s closure-based approach may not optimize for this.
  • Your polymorphic relationships require complex validation or transactions spanning multiple entity types (this package delegates loading to closures, which may bypass Doctrine’s transactional guarantees).
  • You’re using non-Doctrine ORMs (e.g., Eloquent in Laravel) or need multi-database support.
  • You prefer native Doctrine features (e.g., targetEntity in ManyToOne) and don’t mind the overhead of discriminator columns.
  • The package’s maturity is a concern (0 stars, no dependents, minimal documentation). Consider only for greenfield projects or as a proof-of-concept.

How to Pitch It (Stakeholders)

For Executives:

"This package lets us store relationships to multiple entity types (e.g., users, services, or AI agents) in a single column—without complex database schemas or performance hits. For example, a ‘Story’ could be authored by any type of entity, and we’d only need one column to track it. This simplifies our content platform’s flexibility while keeping the database clean. It’s a lightweight ‘buy’ vs. building a custom solution, with minimal risk since it’s MIT-licensed and integrates seamlessly with our existing Symfony/Laravel stack."

Key Benefits:

• Reduces technical debt: Avoids over-engineering polymorphic relationships.
• Future-proofs: Easily add new entity types to relationships without schema migrations.
• Low cost: No dev time to build; minimal maintenance overhead.

For Engineering:

*"The ObjectReferenceBundle solves a common pain point: storing polymorphic references (e.g., Actor could be a User, Organization, or AIModel) in a single column using Doctrine ORM. Here’s how it works:

• Under the hood: Uses a closure to lazily load the referenced object when getActor() is called. The actual ID and type are stored in separate fields (actorId, actorType).
• Pros:
  • No discriminator columns or inheritance tables.
  • Works with Symfony’s dependency injection and Doctrine’s event system.
  • Lightweight (~500 LOC) and MIT-licensed.
• Cons:
  • Not for bulk operations: Each load triggers a closure call (may impact performance in queries with JOIN).
  • Manual field management: You must declare *Id and *Type fields, even if unused.
  • Early-stage: No community adoption yet (0 stars), but the concept is sound.

Recommendation: Pilot this for a non-critical polymorphic relationship (e.g., ‘createdBy’ in audit logs) to validate performance and ease of use before wider adoption. If it works, it could replace ad-hoc JSON columns or complex inheritance setups."*

Alternatives Considered:

• Doctrine’s native polymorphic associations (more overhead, stricter schema).
• Raw JSON columns (less type safety, harder to query).
• Custom repository logic (higher maintenance).