Object Reference Bundle Laravel Package

Product Decisions This Supports

• Polymorphic Relationships: Enables flexible, type-safe polymorphic associations (e.g., a Story referencing either an Actor or Director via a single field) without complex joins or discriminator columns. Reduces boilerplate for polymorphic entities in Doctrine.
• Lazy-Loaded Closures: Supports deferred loading of related objects via closures, improving performance for rarely accessed references (e.g., caching layers or external API lookups).
• Lowered Onboarding Cost (1.1.1): Reference configuration is now derived by reflection rather than a custom mapping key. This removes a per-field configuration step, so teams can adopt the attribute with near-zero mapping overhead and fewer opportunities for misconfiguration — a direct reduction in integration effort for new features.
• Roadmap for "Soft Polymorphism": Justifies building a lightweight abstraction layer for polymorphic relationships before investing in a full ORM extension (e.g., Gedmo Doctrine Extensions). Reflection-based configuration makes this a cheaper first step and a cleaner exit path if the abstraction is later replaced.
• Use Cases:
  • Content Management: Stories with dynamic authors (e.g., Actor, Guest, AI).
  • Audit Trails: Tracking actions by polymorphic users (e.g., Human, ServiceAccount).
  • Legacy Migration: Gradually replacing raw id/type columns with typed references — reflection inference means existing typed properties can be wired up without annotating each one.
• Build vs. Buy: Avoids reinventing polymorphic logic from scratch and now avoids most of the configuration glue too; leverages the existing Doctrine integration for faster iteration.

When to Consider This Package

• Adopt if:
  • Your Laravel/Symfony app uses Doctrine ORM and needs polymorphic relationships with minimal overhead.
  • You prioritize type safety and deferred loading over raw id/type columns.
  • You want minimal configuration surface — as of 1.1.1 the reference setup is inferred via reflection, so the barrier to a first working spike is small.
  • Your team is comfortable with closures for lazy loading (avoids N+1 queries for optional references).
  • You’re not using Eloquent (this is Doctrine-specific; the package ships as a Symfony bundle, so Laravel adoption implies using Doctrine there too).
• Look elsewhere if:
  • You need Eloquent support (consider laravel-polymorphic-relations or custom traits).
  • Your polymorphic use case requires complex query filtering (e.g., filtering by Actor or Director attributes in a single query).
  • You prefer simpler syntax (e.g., morphTo in Eloquent) over Doctrine attributes.
  • You depend on explicit, hand-written mapping keys for auditing or tooling — 1.1.1 shifts configuration to reflection, so verify behavior and plan a regression pass before upgrading existing models.
  • The package’s maturity (still a single-maintainer project with a small release history, now at 1.1.1) is a risk for production-critical systems.

How to Pitch It (Stakeholders)

For Executives: "This package lets us model flexible, type-safe relationships (e.g., a ‘Story’ referencing any ‘ContentCreator’) without bloating our database or writing custom ORM logic. The latest release removes most of the setup work — the library now infers configuration from our existing code — so the cost to trial it on a real feature is a small spike rather than a project. It’s a lightweight alternative to building polymorphic features from scratch, saving dev time while keeping our data architecture clean. Ideal for use cases like dynamic authoring or audit trails where relationships aren’t static."

For Engineers: *"The ObjectReference attribute simplifies polymorphic associations in Doctrine by:

1. Reducing boilerplate: No discriminator columns or complex joins — and since 1.1.1, no custom mapping key either; the reference configuration is derived by reflection from your typed property.
2. Enabling lazy loading: Uses closures to defer object hydration (e.g., for external API calls).
3. Future-proofing: Aligns with Doctrine’s attribute roadmap and avoids vendor lock-in.

Upgrade note: 1.1.1 is a patch release, but it changes where configuration comes from (reflection vs. an explicit mapping key). If any existing model relied on the custom key, run a quick regression on those entities before rolling it out.

Tradeoff: Requires Doctrine (not Eloquent) and assumes comfort with closures. Still early-stage and single-maintainer, but the reflection-based setup makes it cheaper than ever to evaluate."*