Single Table Inheritance Laravel Package

Technical Evaluation

Architecture Fit

• Pros:
  • Aligns well with Laravel’s Eloquent ORM, reducing complexity in polymorphic relationships by consolidating multiple model types into a single table.
  • Supports deep inheritance hierarchies (not just flat parent-child), which is useful for complex domain models (e.g., User, AdminUser, SuperAdminUser).
  • Trait-based design ensures compatibility with other Laravel traits (e.g., SoftDeletes, Validating) without subclassing conflicts.
  • Column customization allows flexibility in database schema design (e.g., using type or model_kind instead of Laravel’s default morph_map).
• Cons:
  • Single-table inheritance (STI) introduces query inefficiencies (e.g., WHERE type = 'AdminUser' filters) compared to class-table inheritance (CTI) or foreign-key associations for deep hierarchies.
  • No built-in support for polymorphic relationships (e.g., MorphTo/MorphMany), which may require additional logic if the package is used alongside Laravel’s native polymorphism.
  • Last release in 2021 raises concerns about long-term maintenance and compatibility with newer Laravel versions (e.g., 10.x).

Integration Feasibility

• Laravel Compatibility:
  • Officially supports Laravel 5.8+, but untested on Laravel 9/10 may pose risks (e.g., PHP 8.1+ features like enums, constructor property promotion).
  • PHP 8.0+ may require adjustments if the package uses deprecated syntax (e.g., create_function).
• Database Schema:
  • Requires a discriminator column (default: type) to store model class names. Migration must be backward-compatible if the column already exists.
  • No schema migrations provided in the package; TPM must define and test these.
• Testing Overhead:
  • STI introduces edge cases (e.g., serialization, polymorphic casts, query caching). Requires comprehensive unit/integration tests for inherited models.

Technical Risk

• High:
  • Performance: STI can bloat tables with NULL columns for unused inherited fields. May require partial indexing or denormalization for large datasets.
  • Query Complexity: Joins or subqueries may become harder to optimize (e.g., WHERE type IN (...) AND ...).
  • Migration Risk: Retrofitting STI into an existing schema (e.g., adding a type column to a live table) requires downtime or careful backfilling.
  • Dependency Risk: No active maintenance since 2021; forking or patching may be necessary for Laravel 10+.
• Mitigation:
  • Benchmark STI vs. alternative patterns (e.g., CTI or foreign-key associations) for the specific use case.
  • Isolate STI models in a dedicated module to limit blast radius.
  • Monitor Laravel updates for breaking changes (e.g., Eloquent query builder optimizations).

Key Questions

1. Why STI?
   • Is the use case truly hierarchical (e.g., Vehicle → Car → ElectricCar), or could foreign-key associations or polymorphic relations suffice?
   • Will the hierarchy grow over time (risking table bloat)?
2. Schema Impact:
   • How will the type column interact with existing indexes/constraints?
   • Are there legacy queries that assume a fixed schema?
3. Performance:
   • What is the expected read/write ratio? STI performs poorly under high-write scenarios with many unused columns.
   • Are there alternatives (e.g., JSON columns for metadata, separate tables with triggers)?
4. Maintenance:
   • Who will triage issues if the package stagnates? (Plan for forking.)
   • How will new Laravel features (e.g., enums, first-class relations) be adopted?
5. Testing:
   • Are there existing tests for polymorphic behavior (e.g., instanceof, serialization)?
   • How will CI/CD pipelines handle STI-specific edge cases?

Integration Approach

Stack Fit

• Laravel Eloquent: Native integration via traits; minimal boilerplate.
• PHP 8.0+: Potential compatibility issues with older PHP features (e.g., array_merge_recursive vs. spread operator).
• Database:
  • MySQL/PostgreSQL: Supports STI natively; indexing strategies may vary.
  • SQLite: May require adjustments for case-sensitive collations.
• Alternatives Considered:
  • Laravel’s Native Polymorphism: Better for "many-to-one" relationships (e.g., Post/Comment morphing to User).
  • Class-Table Inheritance (CTI): Cleaner for deep hierarchies but requires more tables.
  • Foreign-Key Associations: More flexible but loses "inheritance" semantics.

Migration Path

1. Assessment Phase:
   • Audit existing models to identify candidate hierarchies for STI.
   • Prototype a small hierarchy (e.g., User → AdminUser) to validate performance and query patterns.
2. Schema Changes:
   • Add type column (or custom name) to the target table:

     Schema::table('users', function (Blueprint $table) {
         $table->string('type')->nullable()->after('id');
     });
     

   • Backfill existing records with type values (e.g., User::all()->each(fn ($u) => $u->forceFill('type', 'User')->save())).
3. Model Refactor:
   • Apply the trait to parent/child models:

     use Nanigans\SingleTableInheritance\SingleTableInheritance;
     
     class User extends Model {
         use SingleTableInheritance;
     }
     
     class AdminUser extends User {
         // Inherits STI automatically
     }
     

   • Update queries to leverage type (e.g., User::where('type', 'AdminUser')).
4. Testing:
   • Unit tests: Verify instanceof, serialization, and trait conflicts.
   • Integration tests: Test CRUD operations, polymorphic casts, and soft deletes.
   • Load testing: Simulate production traffic to measure query performance.

Compatibility

• With Other Traits:
  • SoftDeletes: Works out-of-the-box (STI trait is designed for this).
  • Validating: Test for validation rule inheritance (e.g., child models overriding parent rules).
  • Observers/Events: May require adjustments if using saved()/deleted() hooks (STI models trigger events for the parent class).
• With Laravel Features:
  • API Resources: Ensure toArray()/toJson() handle type correctly (may need custom casting).
  • Scout/Full-Text Search: STI models may need custom analyzers to index type.
  • Queued Jobs: Serialization/deserialization of STI models must be tested.

Sequencing

1. Phase 1: Proof of Concept
   • Implement STI for one non-critical hierarchy.
   • Validate performance, query patterns, and trait conflicts.
2. Phase 2: Schema Migration
   • Add type column to production tables (with downtime if needed).
   • Backfill data incrementally (e.g., during low-traffic periods).
3. Phase 3: Model Refactor
   • Gradually replace models with STI-enabled versions.
   • Update controllers/services to use new query patterns.
4. Phase 4: Testing & Rollback Plan
   • Deploy to staging with feature flags for gradual rollout.
   • Monitor query performance and error rates.
   • Prepare database rollback script (e.g., drop type column if needed).

Operational Impact

Maintenance

• Pros:
  • Reduced table count simplifies database backups and migrations.
  • Centralized validation (if using Validating trait) reduces duplication.
• Cons:
  • Schema changes become riskier (e.g., adding a column affects all models).
  • Debugging: Stack traces may obscure which "child" model is active (e.g., AdminUser vs. User).
  • Tooling:
    • Laravel Debugbar: May need customization to display type.
    • Schema dumps: Tools like Laravel Forge may not handle STI optimally.

Support

• Common Issues:
  • Query performance: Developers may write inefficient WHERE type IN (...) queries.
  • Serialization: JSON APIs may accidentally expose type or fail to reconstruct models.
  • Type safety: instanceof checks may behave unexpectedly (e.g., AdminUser instanceof User returns true).
• **Documentation