Typed Enum Laravel Package

Product Decisions This Supports

• Type Safety & Bug Prevention: Eliminates runtime errors from magic strings or typos (e.g., UserRole::ADMIN vs. UserRole::Admin). Critical for mission-critical systems like payment processing or user permissions.
• Developer Experience (DX): Enables IDE autocompletion, static analysis (Psalm/PHPStan), and strict equality checks (===), reducing cognitive load and onboarding time for new engineers.
• Build vs. Buy: Justifies adopting this lightweight (~1KB) package over custom solutions or heavier alternatives (e.g., Symfony’s Enum), especially for teams prioritizing minimal dependencies.
• Roadmap for Strongly Typed APIs: Future-proofs APIs/services by enforcing valid states (e.g., OrderStatus::PENDING in API contracts). Aligns with Laravel’s shift toward stricter typing (e.g., type-hinted controllers).
• Testing & Validation: Simplifies unit/integration tests with strict enum comparisons and value resolution, reducing flaky tests tied to loose string comparisons.
• Domain-Driven Design (DDD): Supports ubiquitous language by replacing ambiguous strings with self-documenting enums (e.g., PaymentMethod::CREDIT_CARD instead of 'cc').
• Performance Optimization: Enables compile-time checks for invalid enum usage, catching issues early in the CI pipeline (e.g., GitHub Actions with Psalm).

When to Consider This Package

• Avoid If:
  • PHP < 7.2: Private constants are required for full safety (though protected constants work in 7.2+).
  • Dynamic enums needed: This package is static (constants defined at class level). Use a different solution for runtime-generated enums (e.g., Spatie\Enum).
  • Performance is critical: While overhead is minimal, native PHP 8.1+ enum may be preferable for micro-optimizations.
  • Framework-specific solutions exist: If using Symfony, Laravel’s built-in Enum (v9+) or Doctrine’s EnumType may suffice without extra dependencies.
  • Team lacks PHP 8+ familiarity: Requires understanding of final classes, static methods, and type hints.
• Look Elsewhere If:
  • Nested/enum inheritance is required: This package is designed for simplicity.
  • Serialization/deserialization is a priority: The package lacks built-in JSON/YAML support (though getValue() can be extended).
  • Backward compatibility is critical: Private constants (PHP 7.4+) may break existing access patterns in legacy codebases.
  • Native PHP 8.1+ enums are an option: If upgrading is feasible, native enums may offer better long-term compatibility.

How to Pitch It (Stakeholders)

For Executives/Stakeholders:

"This is a low-cost, high-impact fix for a pervasive class of bugs—invalid or typo-prone values—in our codebase. For example, if our OrderStatus enum accidentally accepts CANCELED instead of CANCELLED, this package would catch it at compile time or via static analysis, saving hours in debugging and QA. It’s also lightweight (no performance impact) and future-proofs our APIs for stricter typing. The cost? A 10-minute composer install and minimal developer training. The payoff? Fewer production incidents, faster onboarding, and cleaner code reviews."

For Engineering Teams:

*"Typed-enum lets us treat enums like first-class citizens in PHP, with:

• Autocompletion & IDE support: No more hunting for valid values in a long switch statement.
• Strict equality checks: === works reliably, unlike loose comparisons with magic strings.
• Psalm integration: Static analysis can now verify enum values at dev time.
• Zero boilerplate: Just extend TypedEnum and define constants—done.

Use case: Replace all define('STATUS_PENDING', 'pending') patterns with Status::PENDING(), and let the compiler/IDE enforce correctness. For teams using PHP 8+, this is a stepping stone to native enum types without rewriting legacy code. Let’s pilot this in the Order and User modules first—high-value areas with frequent status changes."*

For Developers:

*"This is PHP enums done right—simple, type-safe, and IDE-friendly. Key perks:

• No more if ($status === 'pending') headaches: Use if ($status === Status::PENDING) for clarity and safety.
• Resolve values dynamically: Need all enums with value = 'active'? Status::resolve('active') gives you an array.
• Works with Psalm: Annotate your enums as @extends TypedEnum<string> for static type checking.
• Future-proof: If you later migrate to PHP 8.1’s enum, the syntax is nearly identical.

Try it: Replace one enum class this sprint (e.g., UserRole) and compare the diff—you’ll see why this is a no-brainer. Bonus: It’ll make your PRs smaller and reviews faster.*"

For QA/DevOps:

*"This package shifts left a common source of bugs—invalid enum values—by:

• Catching typos at dev time: IDE autocompletion prevents UserRole::ADMIN vs. UserRole::Admin mistakes.
• Reducing flaky tests: Strict equality checks (===) eliminate false positives from loose string comparisons.
• Improving CI feedback: Psalm/PHPStan can fail builds on invalid enum usage, catching issues before staging.

Example: If our PaymentStatus enum is used in 50+ places, this ensures consistency across the board without manual audits."*