Laravel Auto Morph Map Laravel Package

Product Decisions This Supports

• Decoupling Database Schema from Application Namespace: Enables teams to refactor internal namespace structures (e.g., App\Modules\Blog\Post → Blog\Post) without breaking polymorphic relationships in the database. Critical for large-scale applications with modular architectures (e.g., microservices, monoliths with domain-driven design).
• Roadmap for API/Backend Modernization: Supports initiatives to abstract internal implementation details (e.g., moving from App\User to Auth\User or Domain\User) while maintaining backward compatibility with legacy data.
• Build vs. Buy: Avoids reinventing polymorphic mapping logic (e.g., manual morphMap configurations in AppServiceProvider), reducing technical debt and maintenance overhead.
• Use Cases:
  • Legacy System Migration: Safely rename models (e.g., App\OldUser → App\NewUser) without data migration.
  • Multi-Tenant Applications: Standardize polymorphic types across tenants (e.g., Tenant1\Post and Tenant2\Post → both map to Post).
  • Third-Party Integrations: Expose simplified polymorphic types to external APIs (e.g., Commentable → Article or Video instead of App\Modules\Articles\Article).
  • Testing/Stubs: Use short aliases (e.g., User, Post) in unit tests without polluting the global namespace.

When to Consider This Package

• Adopt When:

  • Your application uses polymorphic relationships (e.g., Comment belongs to Post or Video) and you need to decouple database types from class namespaces.
  • You’re refactoring namespaces (e.g., moving to a modular structure) and want to avoid manual morphMap updates across the codebase.
  • You prioritize database stability over namespace flexibility (e.g., avoiding schema migrations for type changes).
  • Your team lacks bandwidth to maintain custom polymorphic mapping logic (e.g., a monolithic morphMap array in a service provider).

• Look Elsewhere If:

  • You don’t use polymorphic relationships (package is irrelevant).
  • Your polymorphic types are static and unlikely to change (manual morphMap is sufficient).
  • You need dynamic polymorphic types (e.g., runtime-generated class names) — this package requires predefined mappings.
  • You’re using Laravel < 5.6 (package targets Laravel 5.6+).
  • Your team prefers explicit control over automated namespace resolution (e.g., for debugging or edge cases).
  • The package’s archived status (no updates since 2021) is a concern for long-term maintenance (consider alternatives like spatie/laravel-polymorphic-relations or custom solutions).

How to Pitch It (Stakeholders)

For Executives/Business Leaders:

"This package lets us simplify and future-proof our database relationships without costly migrations. For example, if we rename App\Blog\Post to Content\Post for better organization, this tool automatically updates the database to reflect the change—saving weeks of manual work and reducing risk. It’s a low-cost, high-impact way to clean up technical debt while keeping our backend flexible for future refactoring."

Key Benefits:

• Reduces refactoring risk: Avoids breaking polymorphic relationships during namespace changes.
• Improves maintainability: Centralizes polymorphic type management, reducing bugs from inconsistent mappings.
• Enables modular growth: Supports domain-driven design and microservices by decoupling internal structure from the database.

For Engineering Teams:

*"This package automates Laravel’s polymorphic type mapping, replacing manual morphMap configurations with a declarative, scalable approach. Instead of hardcoding App\Modules\Blog\Post in every polymorphic relationship, we define short aliases (e.g., BlogPost) in a single config file. This is especially useful for:

• Large codebases with frequent namespace changes.
• Multi-module apps where polymorphic types span different directories.
• APIs that need to expose simplified types to clients.

Trade-offs:

• Archived but stable: Last updated in 2021, but the core functionality is battle-tested. Monitor for forks or alternatives if long-term support is critical.
• Not dynamic: Mappings must be predefined (not ideal for runtime-generated classes).
• Laravel-only: Not applicable if you’re using a different framework.

Recommendation: Pilot this for a non-critical polymorphic relationship (e.g., comments on posts/videos) to validate the workflow before rolling out broadly."*

Implementation Steps:

1. Define aliases in config/automorphmap.php (e.g., App\Models\Blog\Post → BlogPost).
2. Replace manual morphMap in AppServiceProvider with the package’s auto-mapping.
3. Test thoroughly: Verify polymorphic queries (e.g., Comment::where('commentable_type', 'BlogPost')) work as expected.
4. Document the new convention for future developers.