[RFC] [Discussion] BackedEnum::values() - Seeking feedback before formal RFC View as Markdown

Hi Savin,

Thanks for sharing your idea.

Hi internals,

I would like to propose adding a native values() method to the BackedEnum
interface that returns an array of all backing values. Before creating a
formal RFC, I'm seeking feedback on the concept and approach.

== Summary ==

The proposal adds:

    interface BackedEnum {
        public static function values(): array;
    }

This would allow:

    enum Status: string {
        case Active = 'active';
        case Inactive = 'inactive';
    }

    Status::values(); // ['active', 'inactive']

== Motivation ==

This pattern is extremely common in the wild. Based on GitHub code search:

  * ~3,860+ direct implementations of this exact pattern
  * ~20,000-40,000 estimated real usage when accounting for shared traits
  * Used in major frameworks: Symfony core (TypeIdentifier.php),
    Laravel ecosystem
  * Documented by PHP.net: The manual itself shows EnumValuesTrait as
    an example

Common use cases:
  * Database migrations: $table->enum('status', Status::values())
  * Form validation: $validator->rule('status', 'in', Status::values())
  * API responses: ['allowed_statuses' => Status::values()]

I agree, this is a common feature I would like as well.

== Backward Compatibility - Important Discussion Point ==

This is a breaking change. Enums that already define a values() method
will fail with:

    Fatal error: Cannot redeclare BackedEnum::values()

Based on ecosystem research:
  * ~24,000-44,000 enum instances will break
  * All implementations are functionally identical to what's being
proposed
  * Migration is mechanical: just delete the user-defined method

The break is justified because:

  1. Behavior is unchanged - native implementation does exactly what users
     already implemented
  2. Migration is trivial - simply remove the redundant method
  3. Precedent exists - PHP 8.1 native enums broke myclabs/php-enum
     (4.9k stars) similarly
  4. Long-term benefit - standardization, discoverability, elimination
     of boilerplate
  5. No alternative - virtual properties are technically infeasible;
     different name doesn't match community expectations

Here I don't agree!

PHP application especially libraries and frameworks very often have to
support multiple PHP versions. They can't just remove an already
implemented function and drop support for all previous PHP versions at once.

So either, the new function will not be final - to allow getting
overwritten by current implementations - in this case you would need to
run another analytics to check for naming clashes with different
incompatible signature or behavior.

Or it needs to kind of deprecation period or another name.

Just my 2 cents

Marc

Hi internals,

I would like to propose adding a native values() method to the BackedEnum
interface that returns an array of all backing values. Before creating a
formal RFC, I'm seeking feedback on the concept and approach.

== Summary ==

The proposal adds:

interface BackedEnum {
    public static function values(): array;
}

This would allow:

enum Status: string {
    case Active = 'active';
    case Inactive = 'inactive';
}

Status::values(); // ['active', 'inactive']

== Motivation ==

This pattern is extremely common in the wild. Based on GitHub code search:

• ~3,860+ direct implementations of this exact pattern
• ~20,000-40,000 estimated real usage when accounting for shared traits
• Used in major frameworks: Symfony core (TypeIdentifier.php),
  Laravel ecosystem
• Documented by PHP.net: The manual itself shows EnumValuesTrait as
  an example

Common use cases:

• Database migrations: $table->enum('status', Status::values())
• Form validation: $validator->rule('status', 'in', Status::values())
• API responses: ['allowed_statuses' => Status::values()]

== Implementation ==

I have a working implementation with tests:
https://github.com/php/php-src/pull/20398

The implementation:

• Mirrors the existing cases() method structure
• Extracts the value property from each case
• Returns an indexed array (0, 1, 2, ...)
• Only available on BackedEnum, not UnitEnum
• All tests pass

== Backward Compatibility - Important Discussion Point ==

This is a breaking change. Enums that already define a values() method
will fail with:

Fatal error: Cannot redeclare BackedEnum::values()

Based on ecosystem research:

• ~24,000-44,000 enum instances will break
• All implementations are functionally identical to what's being proposed
• Migration is mechanical: just delete the user-defined method

The break is justified because:

1. Behavior is unchanged - native implementation does exactly what users
   already implemented
2. Migration is trivial - simply remove the redundant method
3. Precedent exists - PHP 8.1 native enums broke myclabs/php-enum
   (4.9k stars) similarly
4. Long-term benefit - standardization, discoverability, elimination
   of boilerplate
5. No alternative - virtual properties are technically infeasible;
   different name doesn't match community expectations

== Questions for Discussion ==

1. BC break acceptability: Given the scope and straightforward migration,
   is this break acceptable?

2. Method name: values() matches community usage (3,860+ examples) and
   parallels cases(). Alternatives like getValues() or toArray() were
   considered but seem inferior. Thoughts?

3. Target version: Currently targeting PHP 8.6 (master branch). Is this
   appropriate?

4. Deprecation period: Should we emit E_DEPRECATED in 8.5 and fatal error
   in 9.0? Or accept the break immediately? (Deprecation adds engine
   complexity and delays benefit.)

== Prior Art ==

• Symfony: Uses this pattern in core components
• PHP.net Manual: Documents EnumValuesTrait approach
• TypeScript: Object.values(Enum)
• Python: [e.value for e in Enum]
• myclabs/php-enum: Had values() method (4.9k stars)

== Next Steps ==

If feedback is generally positive, I will:

1. Request RFC karma
2. Create formal RFC on wiki.php.net http://wiki.php.net/
3. Address any concerns raised in this discussion
4. Move to formal voting after discussion period

== Implementation Details ==

For those interested in the technical details, the PR includes:

• Core implementation in zend_enum.c
• Stub file updates
• Comprehensive test coverage (9 test files)
• Reflection support
• Documentation in NEWS and UPGRADING

PR: https://github.com/php/php-src/pull/20398

Looking forward to your feedback!

Best regards, Savin Mikhail
GitHub: @savinmikhail

Hey,

Thanks for this! I would love to see this in core.

2. Method name: values() matches community usage (3,860+ examples) and
   parallels cases(). Alternatives like getValues() or toArray() were
   considered but seem inferior. Thoughts?

values()

1. BC break acceptability: Given the scope and straightforward migration,
   is this break acceptable?

2. Target version: Currently targeting PHP 8.6 (master branch). Is this
   appropriate?

3. Deprecation period: Should we emit E_DEPRECATED in 8.5 and fatal error
   in 9.0? Or accept the break immediately? (Deprecation adds engine
   complexity and delays benefit.)

Perhaps the smoothest way would be to allow from 8.6 redeclaring values(), in the same time deprecate it and break it later (9.0)?

Cheers

Hi internals,

I would like to propose adding a native values() method to the BackedEnum
interface that returns an array of all backing values. Before creating a
formal RFC, I'm seeking feedback on the concept and approach.

== Summary ==

The proposal adds:

interface BackedEnum {
    public static function values(): array;
}

This would allow:

enum Status: string {
    case Active = 'active';
    case Inactive = 'inactive';
}

Status::values(); // ['active', 'inactive']

== Motivation ==

This pattern is extremely common in the wild. Based on GitHub code search:

• ~3,860+ direct implementations of this exact pattern
• ~20,000-40,000 estimated real usage when accounting for shared traits
• Used in major frameworks: Symfony core (TypeIdentifier.php),
  Laravel ecosystem
• Documented by PHP.net: The manual itself shows EnumValuesTrait as
  an example

Correction: The manual does not show an EnumValuesTrait that I can find. There is a comment in the manual that includes this method, but that's not part of the manual proper, and frankly 90% of comments in the manual should be removed. (cf: https://www.php.net/manual/en/language.enumerations.traits.php#129250)

Common use cases:

• Database migrations: $table->enum('status', Status::values())
• Form validation: $validator->rule('status', 'in', Status::values())
• API responses: ['allowed_statuses' => Status::values()]

== Implementation ==

I have a working implementation with tests:
https://github.com/php/php-src/pull/20398

The implementation:

• Mirrors the existing cases() method structure
• Extracts the value property from each case
• Returns an indexed array (0, 1, 2, ...)
• Only available on BackedEnum, not UnitEnum
• All tests pass

I am unclear why this is a major advantage over array_column(Status::cases(), 'value');

== Backward Compatibility - Important Discussion Point ==

This is a breaking change. Enums that already define a values() method
will fail with:

Fatal error: Cannot redeclare BackedEnum::values()

Based on ecosystem research:

• ~24,000-44,000 enum instances will break
• All implementations are functionally identical to what's being proposed
• Migration is mechanical: just delete the user-defined method

This is a hard-stop. There are hundreds of thousands of packages in the wild that need to support multiple PHP versions. Nearly all packaglist packages (which I presume is where you're drawing the research from; either that or GitHub which will give a similar result set) support at least two consecutive versions, if not 4, 5, or 6.

A hard break like this would essentially mean the packages containing those 40,000 enums would be unable to support both PHP 8.5 and 8.6 at the same time. That's simply not an acceptable impact on the ecosystem, regardless of how nice the feature may or may not be.

--Larry Garfield