Enumhancer Ide Helper Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev henzeb/enumhancer-ide-helper
   

   Add to composer.json under autoload-dev:

   "autoload-dev": {
       "psr-4": {
           "": "vendor/"
       },
       "classmap": ["vendor/henzeb/enumhander-ide-helper/"]
   }
   

   Run composer dump-autoload.

2. First Use Case: Create a basic enum (PHP 8.1+):

   // app/Enums/UserRole.php
   namespace App\Enums;
   
   enum UserRole: string
   {
       case ADMIN = 'admin';
       case EDITOR = 'editor';
       case VIEWER = 'viewer';
   }
   

   The package will now provide IDE autocompletion for enum values in real-time.

Implementation Patterns

Workflows

1. IDE Integration:

   • Use UserRole::ADMIN in controllers, services, or Blade templates—your IDE (PHPStorm, VSCode) will auto-suggest enum values.
   • No runtime overhead; purely a dev-time tool.

2. Type Safety:

   • Replace magic strings with enums:

     // Before
     if ($role === 'admin') { ... }
     
     // After
     if ($role === UserRole::ADMIN) { ... }
     

   • IDE will flag invalid comparisons (e.g., UserRole::ADMIN === 'admin').

3. Database/Validation:

   • Use enums in Eloquent models:

     use App\Enums\UserRole;
     
     class User extends Model
     {
         protected $attributes = [
             'role' => UserRole::VIEWER,
         ];
     
         protected $casts = [
             'role' => UserRole::class,
         ];
     }
     

   • Form requests/validation:

     use App\Enums\UserRole;
     use Illuminate\Validation\Rule;
     
     public function rules()
     {
         return [
             'role' => ['required', Rule::in(array_column(UserRole::cases(), 'value'))],
         ];
     }
     

4. Localization:

   • Pair with Laravel’s trans() for human-readable labels:

     // lang/en/user_roles.php
     return [
       'admin' => 'Administrator',
       'editor' => 'Content Editor',
       'viewer' => 'Read-only User',
     ];
     
     // Usage
     trans('user_roles.' . UserRole::ADMIN->value);
     

Integration Tips

• Legacy Code: Gradually replace magic strings by introducing enums in new features, then refactor old code.
• Migrations: Use enum type in migrations (MySQL) or string with validation (PostgreSQL/SQLite):

  Schema::table('users', function (Blueprint $table) {
      $table->string('role')->default(UserRole::VIEWER->value);
  });
  

• APIs: Return enum values as strings in JSON responses; document accepted values in OpenAPI/Swagger.

Gotchas and Tips

Pitfalls

1. PHP Version:

   • Requires PHP 8.1+ (native enums). Avoid on older projects.
   • Workaround: Use spatie/enum or myclabs/php-enum as a fallback.

2. IDE Limitations:

   • VSCode: Ensure php-ide-helper is installed for full autocompletion.
   • PHPStorm: May need manual indexing after adding new enums.
   • Fix: Run composer dump-autoload and restart IDE.

3. Database Schema:

   • MySQL ENUM type is not recommended for enums with >64 values (hard limit).
   • Tip: Use string column with validation for scalability.

4. Backward Compatibility:

   • Enums break serialization/deserialization if not handled:

     // Serialize
     $role->value; // Use value, not the enum object
     
     // Deserialize
     UserRole::from($serializedValue);
     

Debugging

• Autoloading Issues:

  • Verify vendor/autoload-dev.php is included in your IDE’s PHP include path.
  • Run composer dump-autoload --optimize if autocompletion is missing.

• Enum Not Recognized:

  • Check for typos in namespace/class names.
  • Ensure the enum file is in a psr-4 autoloaded directory.

Extension Points

1. Custom IDE Helpers:

   • Extend with @method annotations for static methods:

     /**
      * @method static UserRole from(string $value)
      */
     enum UserRole { ... }
     

2. Dynamic Enums:

   • For enums loaded from config/database, use a factory:

     class DynamicRole extends Enum
     {
         public static function cases(): array
         {
             return config('roles.available');
         }
     }
     

3. Testing:

   • Mock enums in tests:

     $this->partialMock(UserRole::class, ['from'])
         ->shouldReceive('from')
         ->with('invalid')
         ->andThrow(new \InvalidArgumentException());
     

4. Performance:

   • Cache enum instances if used heavily in loops:

     static function allValues(): array
     {
         return array_column(self::cases(), 'value');
     }