Parental Laravel Package

Technical Evaluation

Architecture Fit

• STI (Single Table Inheritance) Alignment: Remains a natural fit for Laravel applications requiring hierarchical data models. The package’s core design—leveraging Laravel’s Eloquent and STI—is unchanged, maintaining alignment with domain-driven designs (e.g., polymorphic entities like Order → SubscriptionOrder).
• Laravel 13.x Synergy: Now officially supports Laravel 13.x, including its event system changes (e.g., whenBooted callbacks). This aligns with Laravel’s latest LTS cycle and future-proofs the package for teams adopting Laravel 13.
• Use Case Suitability:
  • Pros: Continues to excel for shallow inheritance hierarchies and shared attributes with specialized behaviors.
  • Cons: Still poorly suited for deep inheritance (>3 levels) or fine-grained RBAC per subclass. No changes to this fundamental limitation.

Integration Feasibility

• Minimal Boilerplate: Unchanged—replaces manual STI setup with the Parental trait and parental() method. No additional boilerplate introduced in v1.6.0.
• Backward Compatibility:
  • Breaking Change: Critical. The reworked event dispatching logic (registering model events inside whenBooted) may break existing event bindings tied to parent classes. Teams using custom event handlers (e.g., Model::created() on parent models) must test thoroughly or refactor.
  • Non-Breaking: Laravel 13.x compatibility is additive; existing STI implementations remain functional.
• Database Impact: No schema changes required. The type column and validation layers remain unchanged.

Technical Risk

• Data Integrity Risks:
  • Event Dispatching: The new whenBooted requirement may cause:
    • Duplicate Events: If parent/child models both bind to the same event (e.g., created), the child’s event may fire twice. Mitigate by consolidating event logic in a single model or using unless guards.
    • Silent Failures: Custom event handlers relying on parent-class bindings may fail silently until tested. Action Required: Audit all event bindings post-upgrade.
  • Query Performance: Unchanged risks (e.g., OR clauses on type) persist. No new performance pitfalls introduced.
• Testing Overhead:
  • Increased: The event system change necessitates comprehensive testing of model events for all STI models. Prioritize:
    • Event propagation (e.g., created, updated).
    • Polymorphic relationship events (e.g., saved on associated models).
  • Version Lock: Last release in 2026; Laravel 13.x support suggests active maintenance, but long-term support remains tied to Laravel’s LTS cycle.
• Migration Risk:
  • High for Event-Dependent Apps: Teams with complex event-driven workflows (e.g., queues, notifications) face higher risk. Plan for a staging environment test before production rollout.

Key Questions

1. Event-Driven Architecture:
   • Are any parent models binding to Laravel events (e.g., Model::created(), Model::saved())? If yes, how will you refactor to avoid duplicates or silent failures?
   • Example: Does User::created() trigger logic that must not fire for AdminUser?
2. Laravel 13.x Adoption:
   • Is your team already on Laravel 13.x, or is this package upgrade tied to a larger Laravel version bump? Coordinate with other dependency updates (e.g., PHP 8.2+).
3. Polymorphic Relationships:
   • Do subclasses share relationships (e.g., OrderItem for Product/Service)? Test event propagation across these relationships post-upgrade.
4. Third-Party Event Listeners:
   • Are external packages (e.g., Laravel Nova, Filament) listening to model events? These may also require updates.
5. Rollback Plan:
   • If event issues arise, can you revert to v1.5.0? Ensure composer.json allows version pinning (e.g., ^1.5).

Integration Approach

Stack Fit

• Laravel Core:
  • Updated: Now fully compatible with Laravel 13.x, including its event system (whenBooted callbacks). Requires PHP 8.2+ (Laravel 13’s minimum).
  • Impact: No changes to core integration (Eloquent, migrations, query builder), but event handling must be audited.
• PHP Version: Critical Update. Requires PHP 8.2+ (Laravel 13’s baseline). Align your runtime and CI/CD pipelines.
• Database Support: Unchanged (MySQL, PostgreSQL, SQLite, SQL Server). No vendor-specific changes.
• Tooling:
  • Laravel Forge/Vapor: Deployments remain unchanged; package is a composer dependency.
  • CI/CD: Add tests for event propagation (see Operational Impact).
  • Event Testing: Use Laravel’s events:listen and events:subscribe commands to audit bindings.

Migration Path

1. Pre-Migration Audit:
   • Step 1: Identify all parent models binding to events (e.g., User::created()). Use:

     grep -r "Model::created" app/
     

   • Step 2: List all STI models using the Parental trait. Prioritize high-risk models (e.g., those with critical event logic).
2. Pilot Implementation:
   • Step 1: Upgrade to Laravel 13.x and PHP 8.2+ in a staging environment.
   • Step 2: Update composer.json to tightenco/parental:^1.6 and run composer update.
   • Step 3: Test a single STI model (e.g., User → AdminUser) with:
     • Event listeners (e.g., created, updated).
     • Polymorphic relationships.
     • API serialization (JSON responses).
3. Rollout Strategy:
   • Option A (Phased by Event Risk):
     1. Models with no events: Upgrade first (low risk).
     2. Models with parent-only events: Refactor to child models or use unless guards.
     3. Models with complex event chains: Upgrade last; monitor closely.
   • Option B (Big Bang with Rollback Plan):
     • Upgrade all STI models simultaneously in a feature flagged release.
     • Prepare to revert to v1.5.0 if event issues emerge.
4. Database Schema:
   • No changes required. Ensure type column exists and is indexed (as in v1.5).

Compatibility

• Laravel Features:
  • Events:
    • Breaking: Parent model event bindings may now dispatch events twice (parent + child). Example:

      // Before (v1.5): Fires once for AdminUser.
      User::created(function ($user) { ... });
      
      // After (v1.6): May fire twice (User + AdminUser).
      

    • Mitigation: Consolidate logic in child models or use:

      AdminUser::created(function ($user) {
          if ($user->getParentalType() === 'AdminUser') { ... }
      });
      

  • Scopes/Relationships: Unchanged. Test polymorphic associations for event side effects.
• Third-Party Packages:
  • Laravel Nova/Filament: May need updates if they listen to parent model events. Check for STI-aware event handling.
  • Cashier/Invoices: Audit for event bindings tied to parent models (e.g., Invoice::paid()).
• Legacy Code:
  • Replace instanceof checks with parental()->is():

    if ($user->parental()->is('AdminUser')) { ... }
    

  • Avoid binding events to parent classes unless absolutely necessary.

Sequencing

1. Pre-requisites:
   • Upgrade to Laravel 13.x and PHP 8.2+.
   • Backup production database and deploy to staging.
2. Core Integration:
   • Update composer.json and run composer update.
   • Apply use Parental trait to all STI models (no code changes needed beyond event refactoring).
3. Event Refactoring:
   • For each parent model with events:
     • Option 1: Move logic to child models.
     • Option 2: Use unless to prevent duplicates:

       User::created(function ($user) {
           unless($user->parental()->is('User')) { ... }
       });
       

4. Testing:
   • Unit Tests: Verify event propagation for each STI model.
   • Integration Tests: Test API endpoints, queues, and notifications.
   • Load Tests: Check for performance regressions in event-heavy workflows.
5. Deployment:
   • Feature Flag: Use Laravel’s config('features.parental_v1.6') to