Laravel Cti Laravel Package

Technical Evaluation

Architecture Fit

• CTI Pattern Alignment: Perfect fit for Laravel applications requiring strict type hierarchies (e.g., Assessment → Quiz, Survey) where subtypes share a core identity but diverge in attributes. Avoids STI’s schema bloat (nullable columns) and polymorphic relations’ lack of referential integrity.
• Eloquent Synergy: Seamlessly integrates with Eloquent’s query builder, relationships, and events. Supports automatic subtype casting (e.g., Assessment::find(1) returns Quiz if the record matches), reducing manual type-checking logic.
• Database Normalization: Enforces real foreign keys between parent/subtype tables, enabling database-level constraints and complex joins. Ideal for auditable or regulated systems (e.g., financial instruments, healthcare records).
• Future-Proofing: Designed for extensible domains (e.g., SaaS platforms with pluggable feature types). New subtypes can be added without altering the parent schema.

Technical Risk

• Schema Complexity: Requires multi-table design (parent + subtype tables), which may conflict with existing schemas or teams accustomed to STI. Migration effort depends on current architecture.
• Query Performance: Joins are automated but not optimized for every edge case. Subtype queries may generate implicit joins (e.g., Quiz::where(...) joins assessments). Benchmarking required for high-traffic endpoints.
• Learning Curve: Developers must understand CTI-specific configurations (e.g., $subtypeMap, $subtypeTable, discriminator vs. lookup tables). Documentation is thorough but assumes Eloquent familiarity.
• Edge Cases:
  • Missing Subtypes: Configurable behavior for orphaned records (e.g., throw exception, return parent model).
  • Concurrent Writes: Package uses transactions for parent/subtype saves, but race conditions could occur in distributed systems.
  • Legacy Data: Migrating from STI/polymorphic relations may require custom logic for data mapping.

Key Questions

1. Schema Compatibility:
   • Does the current database schema align with CTI’s requirements (e.g., shared id column, foreign keys)?
   • Are there existing polymorphic relations or STI models that could conflict or require migration?
2. Performance Requirements:
   • Are there high-frequency queries on subtype-specific columns that could benefit from denormalization (e.g., caching subtype data)?
   • How does the team’s current query complexity compare to CTI’s automated joins?
3. Team Expertise:
   • Is the team comfortable with multi-table inheritance patterns and Eloquent customizations?
   • Are there database administrators who can enforce foreign key constraints during migrations?
4. Use Case Criticality:
   • Are subtypes mandatory (e.g., every Assessment must be a Quiz or Survey), or optional (e.g., some records may lack subtype data)?
   • Does the application require real-time subtype validation (e.g., rejecting invalid Quiz configurations)?
5. Long-Term Maintenance:
   • How will new subtypes be added over time? Is the team prepared for schema changes?
   • Are there third-party tools (e.g., migrations, backups) that need to account for CTI tables?

Integration Approach

Stack Fit

• Laravel 8–13: Native support with no breaking changes. PHP 8.1+ required for attributes (e.g., #[Subtype] annotations in newer versions).
• Database Compatibility: Works with MySQL, PostgreSQL, SQLite, SQL Server (via Eloquent). No vendor-specific features.
• Ecosystem Integration:
  • Scout: Subtype models can be searchable with custom analyzers.
  • Nova/Livewire: Subtype-specific panels or forms can be built using the package’s type resolution.
  • API Resources: Automatically cast subtypes in responses (e.g., AssessmentResource returns Quiz or Survey data).
• Testing: Includes Pest/PHPUnit tests for core functionality. Custom assertions may be needed for subtype-specific logic.

Migration Path

1. Assessment Phase:
   • Audit existing models for STI/polymorphic patterns that could migrate to CTI.
   • Identify shared vs. subtype-specific attributes (e.g., title vs. passing_score).
   • Design parent/subtype tables with foreign keys (use unsignedBigInteger for id columns).
2. Schema Migration:
   • New Projects: Start with CTI from day one.
   • Existing Projects:
     • Option A (Parallel): Add CTI tables alongside STI/polymorphic data, then migrate records in batches.
     • Option B (Big Bang): Rewrite models to use CTI and migrate data in a single transaction (higher risk).
   • Use Laravel Migrations with Schema::create() for subtype tables and foreign()->references() for constraints.
3. Model Refactoring:
   • Replace use HasSubtypes in parent models and extend SubtypeModel for subtypes.
   • Configure $subtypeMap, $subtypeTable, and discriminator/lookup table settings.
   • Update fillable/casts to inherit from parent or override in subtypes.
4. Query Layer:
   • Replace direct Model::where() calls with CTI-aware queries (e.g., Quiz::where(...) auto-joins assessments).
   • Update relationships to use morphMap or subtype-specific logic if needed.
5. Testing:
   • Write subtype-specific tests for CRUD, events, and relationships.
   • Test edge cases: orphaned records, invalid type IDs, concurrent writes.

Compatibility

• Laravel Features:
  • Events: creating, updating, etc., fire on both parent and subtype models.
  • Relationships: Supports belongsTo, hasOne, etc., with subtype-aware constraints.
  • Observers: Work as expected, but may need custom logic for subtype-specific actions.
• Third-Party Packages:
  • Laravel Debugbar: Shows CTI queries with joined tables.
  • Laravel Telescope: Logs subtype resolution and query joins.
  • Spatie Media Library: Subtype models can have polymorphic media attachments.
• Caching:
  • Subtype labels and type resolution are cached to reduce database lookups.
  • Consider Redis for high-traffic applications to cache subtype data.

Sequencing

1. Phase 1 (Low Risk):
   • Implement CTI for non-critical models (e.g., Assessment → Quiz, Survey).
   • Test with read-heavy workloads first (queries, relationships).
2. Phase 2 (Medium Risk):
   • Add write operations (create/update/delete) with transaction handling.
   • Validate event listeners and observers.
3. Phase 3 (High Risk):
   • Migrate core business logic (e.g., User → AdminUser, CustomerUser).
   • Update APIs and frontend integrations to handle subtype responses.
4. Phase 4 (Ongoing):
   • Monitor query performance and optimize with indexes (e.g., type_id in parent table).
   • Document subtype-specific behaviors for future developers.

Operational Impact

Maintenance

• Schema Changes:
  • Adding a new subtype requires:
    1. Creating a subtype table with foreign key.
    2. Updating the parent’s $subtypeMap.
    3. Extending the subtype model (e.g., class NewSubtype extends SubtypeModel).
  • Zero-downtime migrations possible for new subtypes if using Laravel’s schema changes.
• Deprecation:
  • If a subtype is removed, ensure foreign key constraints allow cascading deletes or set ON DELETE SET NULL.
  • Update $subtypeMap in the parent model.
• Backups:
  • Ensure backups include all CTI tables (parent + subtypes). Use mysqldump or database-specific tools with --tables flag.

Support

• Debugging:
  • Query Logs: Enable DB::enableQueryLog() to inspect auto-generated joins.
  • Type Resolution: Use Model::resolveSubtype() to debug subtype casting issues.
  • Events: Override booted() in models to log subtype-specific actions.
• Common Issues:
  • Orphaned Records: Configure config('cti.missing_subtype') to handle missing subtype data (e.g., return parent model or throw exception).
  • N+1 Queries: Use with() or load() for eager loading subtype relationships.
  • Concurrency: Ensure transactions cover parent/subtype saves to avoid race conditions.
• Documentation:
  • Maintain a runbook for:
    • Schema diagrams of CTI tables.
    • Subtype-specific business