Laravel Morphmap Laravel Package

Technical Evaluation

Architecture Fit

• Polymorphic Relations Use Case: Fits seamlessly into Laravel applications requiring fine-grained control over polymorphic relationships (e.g., a Post model with comments using User and Admin as morph targets, while likes use User and Guest).
• Model-Centric Design: Aligns with Laravel’s Eloquent model architecture, avoiding global overrides to morphMap().
• Extensibility: Enables per-relation customization without modifying core Laravel behavior, reducing coupling.

Integration Feasibility

• Low Friction: No service provider registration or config changes—just a trait and constructor property.
• Backward Compatibility: Works alongside Laravel’s native morphMap(); conflicts are resolved via explicit relation definitions.
• Testing: CI/CD-verified (GitHub Actions) for PHP 8.1+ and Laravel 10/11/12, but no dependent packages suggest untested real-world adoption.

Technical Risk

• Edge Cases:
  • Circular Dependencies: If multiple models reference each other with custom morph maps, validation logic may need adjustments.
  • Performance: Overhead from dynamic morph map resolution per relation (minimal, but measurable in high-throughput systems).
• Version Lock: Tied to Laravel 10/11/12; no support for LTS 9.x or future versions without updates.
• Documentation Gaps: Readme lacks examples for complex scenarios (e.g., nested polymorphic relations or dynamic morph maps).

Key Questions

1. Use Case Validation:
   • Are polymorphic relations in the system heterogeneous enough to justify per-relation maps (vs. global morphMap)?
   • Example: Does a Media model need uploaded_by (users) and shared_with (users/groups) with distinct type aliases?
2. Migration Strategy:
   • How will existing polymorphic data (e.g., morph_type in pivot tables) adapt to new type aliases?
   • Will data migration tools (e.g., Laravel migrations) need to handle backfilling?
3. Testing Coverage:
   • Are there unit/integration tests for the specific polymorphic relationships in the codebase?
   • How will custom morph maps interact with eloquent events (e.g., retrieved, saved)?
4. Long-Term Maintenance:
   • Who will update the package if Laravel evolves polymorphic relation handling?
   • Is the MIT license acceptable for the project’s licensing model?

Integration Approach

Stack Fit

• Laravel 10/11/12: Native support; no conflicts with core features.
• PHP 8.1+: Leverages modern features (e.g., constructor property promotion) for clean syntax.
• Database Agnostic: Works with any Laravel-supported DB (MySQL, PostgreSQL, SQLite) as it’s a logic-layer package.
• Ecosystem Compatibility:
  • ORM: Eloquent-only; no impact on Query Builder or raw SQL.
  • Testing: Playwell with Pest/PHPUnit via Laravel’s testing helpers.
  • Caching: No direct caching layer, but custom morph maps could be cached at the model level if performance-critical.

Migration Path

1. Assessment Phase:
   • Audit all polymorphic relations in the codebase. Identify candidates for custom morph maps (e.g., relations with overlapping but distinct type aliases).
   • Example: Post::morphMany('Comment', Comment::class) vs. Post::morphMany('Like', Like::class) where Comment and Like both use User but need different aliases.
2. Incremental Adoption:
   • Step 1: Add HasCustomMorphMap trait to a single model (e.g., Post) and define $customMorphMap for one relation.
   • Step 2: Test relation queries, serialization (API responses), and database inserts/updates.
   • Step 3: Roll out to other models, prioritizing high-impact relations (e.g., those with serialization or API contracts).
3. Data Migration:
   • If existing data uses global morphMap aliases, create a migration to update morph_type values for affected records.
   • Example:

     DB::table('comments')->where('morph_type', 'User')->update(['morph_type' => 'Author']);
     

4. Deprecation Plan:
   • Phase out global morphMap() in favor of custom maps where applicable.
   • Use feature flags or config to toggle behavior during transition.

Compatibility

• Laravel Features:
  • API Resources: Custom morph maps will affect serialized output; update toArray()/toJson() if type aliases change.
  • Scout/Algolia: If using polymorphic relations for search, ensure custom maps align with searchable attributes.
  • Notifications: Polymorphic notifiable models may need updates if morph types change.
• Third-Party Packages:
  • Laravel Nova/Vue: Custom morph maps may require UI updates if the admin panel relies on morph types.
  • Spatie Media Library: Check if polymorphic attachments use global morphMap.
• Legacy Code:
  • Search for morphMap() calls in config/files and replace with custom maps where needed.

Sequencing

Operational Impact

Maintenance

• Pros:
  • Decoupled: Changes to one relation’s morph map don’t affect others.
  • Explicit: Custom maps make polymorphic behavior self-documenting in the model.
• Cons:
  • Boilerplate: Each model requiring custom maps needs a constructor property.
  • Debugging: Errors may surface in specific relations rather than globally (e.g., "Unknown morph type for likes relation").
• Tooling:
  • Add static analysis (e.g., PHPStan) to detect missing custom morph maps for polymorphic relations.
  • Create a migration helper to validate morph type consistency across the codebase.

Support

• Common Issues:
  • Mismatched Aliases: A relation’s custom map doesn’t match the actual model’s morphClass (e.g., User vs. Author).
  • Serialization Errors: API responses include incorrect type aliases.
  • Database Constraints: Foreign keys or indexes on morph_type may break if aliases change.
• Troubleshooting:
  • Log morph map resolutions for debugging:

    \Log::debug('Custom morph map for relation', ['relation' => $relation->getMorphClass(), 'map' => $this->customMorphMap]);
    

  • Use Laravel’s dd() to inspect relation metadata:

    dd($post->comments()->getMorphMap());
    

• Documentation:
  • Add internal docs for each model’s custom morph maps, including:
    • Relation name → morph type mapping.
    • Examples of valid/invalid morph types.

Scaling

• Performance:
  • Overhead: Minimal per-query (morph map lookup is O(1) for arrays).
  • Bottlenecks: Custom maps add indirection to polymorphic resolution; test under load if using high-frequency relations.
  • Optimizations:
    • Cache custom morph maps at the model level if relations are static.
    • Use static::$customMorphMap instead of instance properties for non-stateful maps.
• Database:
  • Schema Changes: No new tables, but morph_type updates may require downtime for large datasets.
  • Indexes: Ensure morph_type columns are indexed for polymorphic joins.
• Team Scaling:
  • Onboarding: New developers must understand per-relation morph maps; add to the architecture decision records (ADRs).
  • Ownership: Assign a polymorphic relations owner to review changes to custom maps.

Failure Modes