Enumhancer Laravel Package

Technical Evaluation

Architecture Fit

• Strengths:

  • PHP 8.1+ Native Enums: Aligns with Laravel’s modern PHP stack (Laravel 10+ requires PHP 8.1+), reducing abstraction overhead.
  • Framework-Agnostic: Decouples from Laravel-specific solutions (e.g., Spatie’s Laravel Enum), enabling reuse across microservices or non-Laravel PHP projects.
  • Type-Agnostic Design: Avoids backed enums’ complexity (e.g., serialization/deserialization), simplifying domain modeling for value objects.
  • Case-Insensitive Handling: Mitigates naming inconsistencies (e.g., UserRole::ADMIN vs. UserRole::Admin), improving developer experience.
  • Backward Compatibility: Eases migration from Spatie’s PHP Enum (non-Laravel) by mirroring its API where possible.

• Weaknesses:

  • Laravel-Specific Gaps: Missing Laravel integrations (e.g., Eloquent casting, Blade directives, or Laravel Scout compatibility) may require custom wrappers.
  • No Built-in Database/ORM Support: Unlike Spatie’s Laravel package, this lacks native column type casting or query builder methods (e.g., where('status', UserStatus::ACTIVE)).
  • Opportunity Cost: AGPL-3.0 license may conflict with proprietary Laravel projects (consult legal team).

Integration Feasibility

• Laravel Compatibility:
  • High: Core functionality (e.g., enum validation, serialization) integrates seamlessly with Laravel’s request validation, API resources, and DTOs.
  • Medium: Requires manual setup for Eloquent (e.g., custom accessors/mutators) or Blade templating (e.g., @enum directives).
• Testing:
  • PHPUnit: Supports assertions (e.g., assertSameEnum()), but lacks Laravel-specific test helpers (e.g., assertDatabaseHas() with enums).
• Performance:
  • Neutral: Minimal runtime overhead; type-agnostic design avoids backed enum serialization costs but may require manual type hints in some cases.

Technical Risk

• Migration Risk:
  • Low for New Projects: Ideal for greenfield Laravel apps targeting PHP 8.1+.
  • Medium for Legacy Code: Spatie’s Laravel Enum migration may need refactoring (e.g., replacing Spatie\Enum\Laravel\HasEnums traits).
• Dependency Risk:
  • Low: Single package with no external dependencies (beyond PHP 8.1+).
• Future-Proofing:
  • High: Actively maintained (releases in 2026), with clear roadmap for new features (e.g., Laravel integrations in future versions).

Key Questions

1. Laravel-Specific Needs:
   • Does the team require Eloquent column casting, query builder methods, or Blade directives? If yes, will custom wrappers be needed?
2. License Compliance:
   • Is AGPL-3.0 acceptable for the project, or is a MIT/BSD alternative (e.g., Spatie’s Laravel Enum) preferred?
3. Backed vs. Type-Agnostic Enums:
   • Are there use cases requiring backed enums (e.g., database storage with INT/STRING mapping)? If so, this package may not suffice.
4. Team Adoption:
   • Will developers need training on PHP 8.1 enums or Enumhancer’s API (e.g., Enumhancer::fromString() vs. native UserStatus::from())?
5. Testing Strategy:
   • How will enums be tested in CI? Will custom PHPUnit assertions or Laravel’s TestCase helpers be used?

Integration Approach

Stack Fit

• Laravel Core:
  • Request Validation: Replace Spatie\Enum\Enum with Enumhancer\Enum in FormRequest or Validator rules.
  • API Resources: Use enums in JsonResource for consistent serialization (e.g., public function toArray(): array { return ['status' => $this->resource->status->value]; }).
  • DTOs: Leverage enums for immutable data transfer (e.g., UserStatus::ADMIN in CreateUserDto).
• Database Layer:
  • Option 1: Use enums as string constants (e.g., status VARCHAR(255)) with manual validation.
  • Option 2: Create custom Eloquent accessors/mutators for database storage (e.g., getStatusAttribute()).
  • Option 3: Combine with a package like laravel-enum for column casting (if needed).
• Blade/Templating:
  • Implement custom Blade directives (e.g., @enum('UserStatus::ADMIN')) or use PHP directly in views.

Migration Path

1. Assessment Phase:
   • Audit existing enums (Spatie, custom classes, or strings) and categorize by usage (e.g., validation, API responses, database).
2. Pilot Migration:
   • Start with non-critical enums (e.g., API status codes) and replace Spatie\Enum\Enum with Enumhancer\Enum.
   • Example:

     // Before (Spatie)
     use Spatie\Enum\Laravel\Enum;
     
     class UserRole extends Enum {
         public static $values = ['ADMIN', 'USER'];
     }
     
     // After (Enumhancer)
     enum UserRole {
         case ADMIN;
         case USER;
     }
     

3. Laravel-Specific Adjustments:
   • For Eloquent, create a base model trait:

     trait UsesEnums {
         protected function serializeEnum($value) { /* ... */ }
         protected function deserializeEnum($value, $enumClass) { /* ... */ }
     }
     

   • For Blade, publish a custom directive:

     Blade::directive('enum', function ($expression) {
         return "<?php echo {$expression}->value; ?>";
     });
     

4. Testing:
   • Update unit tests to use assertSameEnum() or custom assertions.
   • Add integration tests for enum validation in API endpoints.

Compatibility

• PHP 8.1+: Mandatory; ensure Laravel version (10+) and server environment support.
• Composer: Standard composer require henzeb/enumhancer installation.
• IDE Support: Modern IDEs (PHPStorm, VSCode) auto-complete enums; no additional tooling needed.
• Backward Compatibility:
  • Spatie’s PHP Enum (non-Laravel) APIs are mirrored where possible (e.g., from() methods).
  • Laravel-specific Spatie features (e.g., HasEnums trait) require manual replacement.

Sequencing

1. Phase 1: Replace validation and DTO enums (low risk).
2. Phase 2: Migrate API response enums (impact on consumers).
3. Phase 3: Update database-related enums (highest risk; plan rollback).
4. Phase 4: Refactor Blade templates and views.
5. Phase 5: Optimize performance (e.g., caching enum lookups if needed).

Operational Impact

Maintenance

• Pros:
  • Reduced Boilerplate: Native enums eliminate need for Spatie’s trait-based inheritance.
  • Type Safety: PHP 8.1 enums catch invalid cases at compile time.
  • Future Extensibility: Enumhancer’s roadmap suggests Laravel integrations may reduce custom maintenance.
• Cons:
  • Custom Wrappers: Eloquent/Blade integrations may require ongoing maintenance.
  • Documentation: Team may need to document custom enum usage patterns (e.g., database serialization).

Support

• Developer Onboarding:
  • Low: Familiarity with PHP 8.1 enums reduces learning curve.
  • Medium: Custom Laravel integrations (e.g., accessors) may need internal docs.
• Troubleshooting:
  • Common Issues:
    • Case sensitivity in database queries (mitigate with strtolower() in queries).
    • Serialization edge cases (e.g., JSON API responses; use ->value explicitly).
  • Debugging Tools: Leverage var_dump($enum->value) or Enumhancer::getAll() for inspection.

Scaling

• Performance:
  • Neutral: Enums are lightweight; no significant scaling impact.
  • Optimizations:
    • Cache enum instances if used frequently in high-throughput APIs.
    • Avoid backed enums for large datasets (type-agnostic design minimizes overhead).
• Database:
  • String Storage: Enums stored as strings (e.g., VARCHAR) scale similarly to existing solutions.
  • Indexing: Ensure database columns are indexed for enum-based queries.

Failure Modes

• Runtime Errors:
  • Invalid Enum Values: PHP 8.1 enums throw ValueError for invalid cases; ensure validation layers (e.g