Add values() Method to BackedEnum

Summary

Introduce a native BackedEnum::values() static method that returns the list of all backing values (int|string) of a backed enum's cases in declaration order. This eliminates boilerplate commonly implemented across projects and aligns with the existing cases() API.

The interface declares the method without a return type to ensure zero backward compatibility breaks with 6,800+ existing implementations.

Target: master (PHP 8.6)

Motivation

The ecosystem repeatedly implements the same pattern to produce an array of enum values:

enum Status: string {
    case Draft = 'draft';
    case Published = 'published';

    // Boilerplate implemented in countless codebases today
    public static function values(): array {
        return array_column(self::cases(), 'value');
    }
}

This pattern appears widely across GitHub and frameworks, often implemented directly or via traits (which hides usage from code search).

Quantitative Evidence

Direct implementations (comprehensive GitHub code search as of 2025-11-12):

Implementation distribution:

• array_column pattern: 3,600 (48%) - most popular ✨
• array_map patterns: 2,554 (34%)
• Other patterns: 1,306 (18%)

Trait pattern multiplier (2,900 results):

• Many projects factor this into a trait (e.g., EnumValuesTrait) and then use it in dozens of enums
• Direct search counts significantly understate total usage
• Conservative estimate: 20,000-40,000 total implementations in the ecosystem

Qualitative evidence (frameworks & libraries):

• symfony/symfony usage
• box-project/box usage
• Legacy library values() method (pre-8.1 enums)

Providing a native values() method:

• Removes boilerplate and fragmentation (different traits/implementations)
• Improves discoverability and consistency (parallels cases() nicely)
• Simplifies migrations from legacy enum libraries and existing project traits

Proposal

Add the following method to the BackedEnum interface:

interface BackedEnum extends UnitEnum
{
    /**
     * Returns an indexed array of all backing values for the enum cases.
     *
     * @return int[]|string[]
     */
    public static function values();
}

Semantics

• Available only for backed enums (int|string). Not available on unit enums.
• Returns a 0-based, indexed array of the backing values in declaration order.
• For int-backed enums, returns array<int>; for string-backed, array<string>.

Examples

enum Priority: int {
    case Low = 1;
    case High = 10;
}
Priority::values(); // [1, 10]

enum Color: string {
    case Red = 'red';
    case Blue = 'blue';
}
Color::values(); // ['red', 'blue']

Implementation

The interface declares the method without a return type to ensure zero backward compatibility breaks:

interface BackedEnum extends UnitEnum
{
    /**
     * Returns an indexed array of all backing values for the enum cases.
     *
     * @return int[]|string[]
     */
    public static function values();  // ← NO return type in interface
}

Characteristics:

• ✅ Zero BC breaks - all existing implementations remain compatible
• ✅ Native implementation returns array - proper type at runtime
• ✅ Docblock provides type information for static analysis
• ✅ Allows implementations to specify any return type or none
• ✅ All 6,800+ existing userland implementations continue working unchanged

Backward Compatibility Analysis

Comprehensive GitHub search analysis (2025-11-12) of existing values() implementations:

Backward Compatibility

BC Breaks: ✅ ZERO (0%)

By omitting the return type from the interface, all existing implementations remain compatible. The native implementation always returns array, but user-defined implementations can use any return type:

// All of these are compatible:
public static function values(): array { }      // ✅ Compatible
public static function values() { }             // ✅ Compatible
public static function values(): string { }     // ✅ Compatible (though semantically wrong)

Comprehensive GitHub search analysis (2025-11-12) found 6,800 existing values() implementations:

• 91.2% (6,200) already have : array return type
• 0.9% (64) have no return type
• 0.1% (7) have incompatible return types (: string, : Iterator, etc.)
• All continue working without changes

Implementation Details

Engine changes (Zend)

Add stub and arginfo:

• Zend/zend_enum.stub.php: add BackedEnum::values() signature without return type

  public static function values();

• Zend/zend_enum_arginfo.h: regenerated (committed)

Add interned string identifier:

• Zend/zend_string.h: add ZEND_STR_VALUES ("values")

Implement and register the method:

• Zend/zend_enum.c:
  • Implement zend_enum_values_func(), extracting the value property from each case
  • Register for all backed enums
  • Native implementation always returns array regardless of interface declaration

Tests

Reflection tests:

• ext/reflection/tests/BackedEnum_values_reflection.phpt - ensure method appears
• ext/reflection/tests/ReflectionEnum_toString_backed_int.phpt - update toString
• ext/reflection/tests/ReflectionEnum_toString_backed_string.phpt - update toString

Enum behavior tests:

• Zend/tests/enum/backed-values-int.phpt - int-backed enum values
• Zend/tests/enum/backed-values-string.phpt - string-backed enum values
• Zend/tests/enum/backed-values-empty.phpt - empty enum edge case
• Zend/tests/enum/backed-values-order.phpt - declaration order preservation
• Zend/tests/enum/backed-values-not-on-pure.phpt - pure enums don't have values()
• Zend/tests/enum/backed-values-ignore-regular-consts.phpt - regular constants ignored
• Zend/tests/enum/backed-values-user-defined.phpt - user-defined values() overrides native
• Zend/tests/enum/backed-values-user-defined-incompatible.phpt - different return types allowed

Documentation in-tree

• NEWS: announce the feature under Core
• UPGRADING: List under "New Features" (no BC section needed - zero breaks)

Manual (php/doc-en)

To be added in a separate PR:

• BackedEnum interface page: values() signature, description, examples
• Enumerations guide: mention values() alongside cases()/from()/tryFrom()
• Migration guide for 8.6: add entry for BackedEnum::values()

Performance

Native implementation provides:

• O(n) complexity over number of cases
• Similar performance to array_column(self::cases(), 'value')
• No userland call overhead

Benchmark (100,000 iterations):

array_column: 0.012s
array_map:    0.035s (2.9x slower)
native:       ~0.012s (similar to array_column)

Reference: https://3v4l.org/Q5AYg

Note: array_column is the most popular pattern (48% of implementations, 3,600 results) and is ~3x faster than array_map.

Alternatives Considered

Different method name

• getValues(), valueList(): More verbose, doesn't match cases() style
• toArray(): Ambiguous - case objects or values? Names or values?

Decision: values() best matches:

• Existing community usage (7,460+ examples)
• Parallel naming with cases()
• Simplicity and clarity

Virtual/magic properties

Status::$values instead of Status::values()

Rejected:

• Enums cannot have static properties
• Inconsistent with cases(), from(), tryFrom() (all methods)

Impact on Ecosystem

Positive impacts

• ✅ 100% of implementations (6,800+) continue working unchanged
• ✅ Zero BC breaks - no migration needed
• ✅ Zero ecosystem disruption
• ✅ Native implementation returns proper array type
• ✅ New enums automatically get values() without boilerplate
• ✅ Standardization reduces ecosystem fragmentation
• ✅ Improved discoverability for new developers
• ✅ Simplified documentation (single standard approach)
• ✅ Can add stricter typing in PHP 9.0 if desired

Rejected Features

Interface WITH Return Type (: array)

An alternative approach was considered where the interface would explicitly declare : array return type:

interface BackedEnum extends UnitEnum
{
    public static function values(): array;  // ← WITH return type
}

Advantages:

• Full type safety in interface contract
• Better IDE inference and autocomplete
• Consistent with modern PHP practices
• Matches cases(): array signature

Why rejected:

This approach would cause BC breaks affecting 1.0-8.8% of existing implementations (71-600 codebases):

Example breaking code:

enum Status: string {
    case Active = 'active';

    public static function values() {  // ❌ Missing : array
        return array_column(self::cases(), 'value');
    }
}
// Fatal error: Declaration of Status::values() must be compatible
// with BackedEnum::values(): array

While 91.2% of implementations already have the correct signature, breaking even 1-9% of the ecosystem was deemed unacceptable for a convenience feature. The chosen approach (no return type) provides the same functionality with zero disruption.

This stricter typing could be reconsidered for PHP 9.0, where major BC breaks are more acceptable, with a deprecation period in PHP 8.x.

Prior Art

No previous RFCs proposing a BackedEnum::values() method were found.

Related RFCs

Review of the PHP RFC index shows enum-related proposals:

• Add get_declared_enums() function (2024)
• Fetch properties of enums in const expressions (2022)
• Enumerations (2020)
• Allow static properties in enums (2021)
• Auto-implement Stringable for string backed enums (2022)
• Sorting enum (2021)

None address adding a convenience method returning backing values.

Other languages

• TypeScript: Object.values(EnumType)
• Python: [e.value for e in EnumType]
• myclabs/php-enum (legacy): Had values() method (4,900 stars, pre-8.1)

Checklist

• Engine implementation
• Arginfo generated and committed
• Tests added (enum + reflection + user-defined overrides)
• NEWS and UPGRADING updated
• Zero BC breaks confirmed
• Comprehensive BC analysis with GitHub searches
• Manual docs (php/doc-en) PR to be submitted after review

Links

• RFC: https://wiki.php.net/rfc/add_values_method_to_backed_enum
• Discussion: https://externals.io/message/129186
• Pre-RFC Discussion: https://externals.io/message/129107
• Implementation: Add values() Method to BackedEnum #20398

Thank you for reviewing!