Laravel Morphmap Laravel Package

Product Decisions This Supports

• Polymorphic Relationship Flexibility: Enables teams to implement domain-specific polymorphic relationships (e.g., a Post model with Comment and Reply relations using different morph maps for distinct business logic).
• Avoiding Global Overrides: Justifies build vs. buy for teams frustrated with Laravel’s default global morphMap() behavior, reducing technical debt from monolithic type mappings.
• Multi-Tenant or Multi-Context Apps: Critical for systems where polymorphic types vary by tenant, region, or feature flag (e.g., User vs. Admin in a SaaS platform).
• Legacy Migration: Supports phased refactoring of polymorphic relationships without breaking existing queries during transitions.
• Roadmap for Complex Polymorphic Systems: Aligns with future needs for fine-grained polymorphic control (e.g., AI-generated content vs. user-generated content with distinct type handling).

When to Consider This Package

• Adopt if:

  • Your model has multiple polymorphic relations requiring distinct type aliases (e.g., Post::morphWith('comments') vs. Post::morphWith('reactions')).
  • You’re blocked by Laravel’s global morphMap and need per-relation customization without forking the framework.
  • Your team prioritizes cleaner, more maintainable polymorphic logic over workarounds (e.g., duplicate models or query scopes).
  • You’re using Laravel 8+ and need minimal setup (trait-based, no service provider).

• Look elsewhere if:

  • You only need one polymorphic type per model (default Laravel suffices).
  • Your polymorphic relationships are static and uniform across all contexts.
  • You’re on Laravel <8 (package requires PHP 8.0+).
  • Your team lacks PHP/Laravel expertise to debug custom morph map edge cases (e.g., eager loading quirks).

How to Pitch It (Stakeholders)

For Executives:

"This package lets us treat different polymorphic relationships independently—critical for scaling features like [X use case]. For example, if our Activity model tracks both UserActions and SystemEvents, we can now map them with domain-specific aliases without global hacks. This reduces technical friction for [team] and future-proofs our architecture for [business goal]."

ROI:

• Time Saved: Eliminates workarounds (e.g., duplicate models, complex query logic).
• Risk Reduction: Avoids polymorphic type collisions in multi-tenant or complex systems.
• Cost: Free (MIT license), minimal dev time (trait + config).

For Engineers:

"Laravel’s morphMap is global, but we often need per-relation type mappings. This package lets us define custom maps per relationship (e.g., Post::comments() uses ['Comment', 'Reply'] while Post::tags() uses ['Tag', 'Hashtag']).

• How it works: Add HasCustomMorphMap trait + $customMorphMap array to your model. No service provider needed.
• Why now? Fixes [specific pain point, e.g., ‘our polymorphic queries break when adding new types’].
• Trade-offs: Tiny overhead (~50 lines of code), but no more global overrides.

Example:

class Post extends Model {
    use HasCustomMorphMap;

    protected $customMorphMap = [
        'comments' => ['Comment' => 'comment', 'Reply' => 'reply'],
        'tags'     => ['Tag' => 'tag', 'Hashtag' => 'hashtag'],
    ];
}
```*
**Next Steps**: Spike this in [X days] to validate against [specific use case]. If successful, we can roll it out to [Y models]."