Laravel Lift Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Attribute-based model configuration aligns with modern PHP (PHP 8.0+) and Laravel’s evolving patterns, reducing boilerplate in Eloquent models.
  • Type safety via Cast attributes improves developer experience and runtime correctness, especially for complex data types (e.g., CarbonImmutable, nested arrays).
  • Immutable properties enforce domain-driven design (DDD) invariants at the model layer, reducing accidental state mutations.
  • Event-driven relationships (Watch attribute) enable fine-grained reactivity (e.g., triggering custom events for specific property changes), useful for audit logs or workflows.
  • Relationships as attributes simplify model definitions, though this may conflict with existing Laravel conventions (e.g., dynamic relationship methods).

• Cons:

  • Experimental status introduces technical debt risk; breaking changes are likely until v1.0.
  • Attribute overhead: Reflection-based attribute parsing may impact performance in high-throughput systems (e.g., bulk operations).
  • Limited adoption (0 dependents) suggests unproven scalability or niche use cases.
  • Potential conflicts with existing Laravel features (e.g., $casts, $fillable arrays) if not migrated incrementally.

Integration Feasibility

• Laravel Compatibility: Works with Laravel 10+ (per badge), but no backward compatibility guarantees due to experimental status.
• Database Agnostic: Supports custom connections/tables via #[DB], but complex migrations (e.g., schema changes) may require manual intervention.
• Testing Impact: Attribute-based logic complicates unit testing (e.g., mocking model events or casts). May need custom test utilities.
• IDE Support: Full IntelliSense for attributes (e.g., #[Cast]) requires PHP 8.0+ and modern IDEs (PhpStorm/VSCode).

Technical Risk

• Reflection Performance: Attribute parsing adds runtime overhead. Benchmark critical paths (e.g., bulk create()).
• Event System: Custom events (Watch) may introduce tight coupling if overused. Evaluate event dispatching costs in high-frequency systems.
• Immutability Enforcement: Runtime exceptions (ImmutablePropertyException) could disrupt debugging flows if not handled gracefully.
• Migration Path: Existing models with $casts, $fillable, etc., will require dual maintenance during transition.
• Vendor Lock-in: Heavy reliance on Lift’s trait/methods (e.g., castAndCreate) may complicate future Laravel upgrades.

Key Questions

1. Adoption Strategy:
   • Should Lift be adopted incrementally (e.g., new models only) or big-bang (full migration)?
   • How will existing $casts, $fillable, etc., be deprecated/merged?
2. Performance:
   • Have benchmarks been run against vanilla Eloquent for critical operations (e.g., create(), update())?
   • What’s the impact of attribute reflection in bulk operations (e.g., Model::insert())?
3. Error Handling:
   • How will ImmutablePropertyException and validation errors be surfaced to APIs/clients?
   • Are there fallback mechanisms for unsupported PHP/Laravel versions?
4. Testing:
   • How will attribute-based logic be tested in CI/CD? (e.g., mocking events, casts).
   • Are there known edge cases (e.g., circular relationships, nested attributes)?
5. Long-Term Viability:
   • What’s the roadmap for v1.0 stability? Will Laravel core adopt similar patterns?
   • Are there plans for first-class support in Laravel’s ecosystem (e.g., IDE plugins, debuggers)?

Integration Approach

Stack Fit

• PHP/Laravel: Ideal for new Laravel 10+ projects or greenfield features. Avoid in legacy systems with heavy Eloquent customizations.
• TypeScript/JS Interop: Works seamlessly with Laravel’s API layer (e.g., typed responses via Cast attributes).
• Database: Compatible with all Laravel-supported databases (MySQL, PostgreSQL, SQLite, etc.), but no ORM-specific optimizations (e.g., no PostgreSQL JSONB shortcuts).
• Testing: Integrates with Pest/PHPUnit via standard Eloquent assertions, but may require custom factories for attribute-based models.

Migration Path

1. Phase 1: Pilot Models
   • Start with non-critical models (e.g., Product, UserProfile) to validate:
     • Attribute syntax familiarity.
     • Performance impact.
     • Event/immutability behavior.
   • Use feature flags to toggle Lift usage per model.
2. Phase 2: Incremental Replacement
   • Replace $casts, $fillable, etc., with attributes one model at a time.
   • Example:

     // Before
     protected $casts = ['price' => 'float'];
     protected $fillable = ['name', 'price'];
     
     // After
     #[Cast('float')]
     #[Fillable]
     public float $price;
     

   • Update tests and factories to use Lift’s methods (e.g., castAndCreate).
3. Phase 3: Full Adoption
   • Deprecate legacy model configurations via Laravel’s shouldUseNewAttributes() or custom trait.
   • Refactor dynamic relationships (e.g., hasManyThrough) to attributes if beneficial.
4. Fallback Strategy
   • Maintain dual configuration during transition:

     use WendellAdriel\Lift\Lift;
     
     final class Product extends Model {
         use Lift;
     
         // Lift attributes
         #[Cast('float')]
         public float $price;
     
         // Legacy fallback (if needed)
         protected $casts = ['price' => 'float'];
     }
     

Compatibility

• Laravel Packages:
  • Potential Conflicts: Packages using Eloquent model events (e.g., observables, audit-trail) may need updates to handle Lift’s custom events (Watch).
  • Testing: Verify compatibility with:
    • spatie/laravel-medialibrary (custom casts).
    • laravel-breeze/laravel-jetstream (auth models).
• PHP Extensions:
  • Requires PHP 8.0+ (for attributes). Use php-version checks in composer.json.
• Database:
  • No schema changes required, but column defaults (#[Column(default: ...)]) must match DB constraints.

Sequencing

1. Prerequisites:
   • Upgrade to Laravel 10+ and PHP 8.0+.
   • Audit existing models for conflicting configurations (e.g., $guarded, $hidden).
2. Order of Adoption:
   • Start with DTO-like models (e.g., OrderItem, InvoiceLine) where type safety is critical.
   • Avoid high-churn models (e.g., ActivityLog) until stability is proven.
3. Critical Path:
   • API Contracts: Update OpenAPI/Swagger specs to reflect typed properties.
   • Validation: Replace FormRequest rules with #[Rules] attributes where applicable.
4. Rollback Plan:
   • Keep a backup of legacy model configurations.
   • Use composer scripts to revert Lift traits if needed:

     composer require wendelladriel/laravel-lift --dev  # Temporarily remove
     

Operational Impact

Maintenance

• Pros:
  • Reduced boilerplate lowers maintenance costs for model configurations.
  • Centralized validation/rules (#[Rules]) simplifies updates (e.g., changing max:255 to max:500).
  • Immutability reduces bugs from accidental state changes.
• Cons:
  • Attribute sprawl: Models may become harder to read with many attributes.
  • Debugging complexity: Stack traces for ImmutablePropertyException or event failures may be less intuitive than traditional Eloquent errors.
  • Vendor maintenance: Depend on a single maintainer (WendellAdriel) for critical updates.

Support

• Developer Onboarding:
  • Pros: Attributes make model behavior self-documenting (e.g., #[Cast('float')] clarifies intent).
  • Cons: Requires familiarity with PHP 8.0+ attributes and Lift’s custom methods (castAndCreate).
  • Training: Document attribute patterns in a style guide (e.g., "Use #[Immutable] for IDs").
• Production Issues:
  • Common Failure Modes:
    • Type mismatches: Cast failures during create()/update() (e.g., passing a string to an int field).
    • Event storms: Unhandled Watch events causing performance spikes.
    • Immutability violations: Runtime exceptions during bulk operations.
  • Monitoring: Track:
    • ImmutablePropertyException occurrences.
    • Event