Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:129107
Precedence: list
MIME-Version: 1.0
Date: Thu, 6 Nov 2025 07:09:18 +0300
Message-ID: <CAJYrtd-6ikRT2X5NZHCbC6UsX1VRn2R5pTT4hb-r-YujYjTHqQ@mail.gmail.com>
Subject: [PHP-DEV] [RFC] [Discussion] BackedEnum::values() - Seeking feedback before formal RFC
To: internals@lists.php.net
Content-Type: multipart/alternative; boundary="0000000000003fa80c0642e53b42"
From: mikhail.d.savin@gmail.com (Mikhail Savin)

--0000000000003fa80c0642e53b42
Content-Type: text/plain; charset="UTF-8"

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
  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

--0000000000003fa80c0642e53b42
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr">Hi internals,<br><br>I would like to propose adding a nati=
ve values() method to the BackedEnum<br>interface that returns an array of =
all backing values. Before creating a<br>formal RFC, I&#39;m seeking feedba=
ck on the concept and approach.<br><br>=3D=3D Summary =3D=3D<br><br>The pro=
posal adds:<br><br>=C2=A0 =C2=A0 interface BackedEnum {<br>=C2=A0 =C2=A0 =
=C2=A0 =C2=A0 public static function values(): array;<br>=C2=A0 =C2=A0 }<br=
><br>This would allow:<br><br>=C2=A0 =C2=A0 enum Status: string {<br>=C2=A0=
 =C2=A0 =C2=A0 =C2=A0 case Active =3D &#39;active&#39;;<br>=C2=A0 =C2=A0 =
=C2=A0 =C2=A0 case Inactive =3D &#39;inactive&#39;;<br>=C2=A0 =C2=A0 }<br>=
=C2=A0 =C2=A0<br>=C2=A0 =C2=A0 Status::values(); // [&#39;active&#39;, &#39=
;inactive&#39;]<br><br>=3D=3D Motivation =3D=3D<br><br>This pattern is extr=
emely common in the wild. Based on GitHub code search:<br><br>=C2=A0 * ~3,8=
60+ direct implementations of this exact pattern<br>=C2=A0 * ~20,000-40,000=
 estimated real usage when accounting for shared traits<br>=C2=A0 * Used in=
 major frameworks: Symfony core (TypeIdentifier.php),<br>=C2=A0 =C2=A0 Lara=
vel ecosystem<br>=C2=A0 * Documented by PHP.net: The manual itself shows En=
umValuesTrait as<br>=C2=A0 =C2=A0 an example<br><br>Common use cases:<br>=
=C2=A0 * Database migrations: $table-&gt;enum(&#39;status&#39;, Status::val=
ues())<br>=C2=A0 * Form validation: $validator-&gt;rule(&#39;status&#39;, &=
#39;in&#39;, Status::values())<br>=C2=A0 * API responses: [&#39;allowed_sta=
tuses&#39; =3D&gt; Status::values()]<br><br>=3D=3D Implementation =3D=3D<br=
><br>I have a working implementation with tests:<br><a href=3D"https://gith=
ub.com/php/php-src/pull/20398" target=3D"_blank">https://github.com/php/php=
-src/pull/20398</a><br><br>The implementation:<br>=C2=A0 * Mirrors the exis=
ting cases() method structure<br>=C2=A0 * Extracts the value property from =
each case<br>=C2=A0 * Returns an indexed array (0, 1, 2, ...)<br>=C2=A0 * O=
nly available on BackedEnum, not UnitEnum<br>=C2=A0 * All tests pass<br><br=
>=3D=3D Backward Compatibility - Important Discussion Point =3D=3D<br><br>T=
his is a breaking change. Enums that already define a values() method<br>wi=
ll fail with:<br><br>=C2=A0 =C2=A0 Fatal error: Cannot redeclare BackedEnum=
::values()<br><br>Based on ecosystem research:<br>=C2=A0 * ~24,000-44,000 e=
num instances will break<br>=C2=A0 * All implementations are functionally i=
dentical to what&#39;s being proposed<br>=C2=A0 * Migration is mechanical: =
just delete the user-defined method<br><br>The break is justified because:<=
br><br>=C2=A0 1. Behavior is unchanged - native implementation does exactly=
 what users<br>=C2=A0 =C2=A0 =C2=A0already implemented<br>=C2=A0 2. Migrati=
on is trivial - simply remove the redundant method<br>=C2=A0 3. Precedent e=
xists - PHP 8.1 native enums broke myclabs/php-enum<br>=C2=A0 =C2=A0 =C2=A0=
(4.9k stars) similarly<br>=C2=A0 4. Long-term benefit - standardization, di=
scoverability, elimination<br>=C2=A0 =C2=A0 =C2=A0of boilerplate<br>=C2=A0 =
5. No alternative - virtual properties are technically infeasible;<br>=C2=
=A0 =C2=A0 =C2=A0different name doesn&#39;t match community expectations<br=
><br>=3D=3D Questions for Discussion =3D=3D<br><br>1. BC break acceptabilit=
y: Given the scope and straightforward migration,<br>=C2=A0 =C2=A0is this b=
reak acceptable?<br><br>2. Method name: values() matches community usage (3=
,860+ examples) and<br>=C2=A0 =C2=A0parallels cases(). Alternatives like ge=
tValues() or toArray() were<br>=C2=A0 =C2=A0considered but seem inferior. T=
houghts?<br><br>3. Target version: Currently targeting PHP 8.6 (master bran=
ch). Is this<br>=C2=A0 =C2=A0appropriate?<br><br>4. Deprecation period: Sho=
uld we emit E_DEPRECATED in 8.5 and fatal error<br>=C2=A0 =C2=A0in 9.0? Or =
accept the break immediately? (Deprecation adds engine<br>=C2=A0 =C2=A0comp=
lexity and delays benefit.)<br><br>=3D=3D Prior Art =3D=3D<br><br>=C2=A0 * =
Symfony: Uses this pattern in core components<br>=C2=A0 * PHP.net Manual: D=
ocuments EnumValuesTrait approach<br>=C2=A0 * TypeScript: Object.values(Enu=
m)<br>=C2=A0 * Python: [e.value for e in Enum]<br>=C2=A0 * myclabs/php-enum=
: Had values() method (4.9k stars)<br><br>=3D=3D Next Steps =3D=3D<br><br>I=
f feedback is generally positive, I will:<br>=C2=A0 1. Request RFC karma<br=
>=C2=A0 2. Create formal RFC on=C2=A0<a href=3D"http://wiki.php.net/" targe=
t=3D"_blank">wiki.php.net</a><br>=C2=A0 3. Address any concerns raised in t=
his discussion<br>=C2=A0 4. Move to formal voting after discussion period<b=
r><br>=3D=3D Implementation Details =3D=3D<br><br>For those interested in t=
he technical details, the PR includes:<br>=C2=A0 * Core implementation in z=
end_enum.c<br>=C2=A0 * Stub file updates<br>=C2=A0 * Comprehensive test cov=
erage (9 test files)<br>=C2=A0 * Reflection support<br>=C2=A0 * Documentati=
on in NEWS and UPGRADING<br><br>PR:=C2=A0<a href=3D"https://github.com/php/=
php-src/pull/20398" target=3D"_blank">https://github.com/php/php-src/pull/2=
0398</a><div><br>Looking forward to your feedback!<br><br>Best regards, Sav=
in Mikhail<br>GitHub: @savinmikhail</div></div>

--0000000000003fa80c0642e53b42--