====== PHP RFC: Debugable Enums ======
  * Version: 0.3
  * Date: 2026-03-12
  * Author: Daniel Scherzer, daniel.e.scherzer@gmail.com
  * Status: In voting
  * Implementation: https://github.com/php/php-src/pull/21425
  * Discussion thread: https://news-web.php.net/php.internals/130303

===== Introduction =====

Enumerations (enums) were introduced in PHP 8.1 ([[rfc:enumerations]]). The RFC specified that magic methods other than <php>__call()</php>, <php>__callStatic()</php>, and <php>__invoke()</php> would not be permitted in enums, noting that most other magic methods involve state, which enum instances do not have. However, the exclusion also applies to <php>__debugInfo()</php>, which does not need to involve state. This RFC proposes allowing the <php>__debugInfo()</php> magic method on enums.

<PHP>
<?php

enum Foo: string {
	case Bar = "Baz";

	public function __debugInfo() {
		return [__CLASS__ . '::' . $this->name . ' = ' . $this->value];
	}
}

var_dump(Foo::Bar);

?>
</PHP>

produces the output

<code>
enum(Foo::Bar) (1) {
  [0]=>
  string(14) "Foo::Bar = Baz"
}
</code>

===== Proposal =====
The error when trying to implement <php>__debugInfo()</php> on an enumeration is removed. The default validation of that magic method (visibility, arguments, return type) is applied if the method is present.

==== Examples ====

Simple example for a unit enum:
<PHP>
<?php

enum Foo {
	case Bar;

	public function __debugInfo() {
		return [$this->name . ' is a case of the ' . __CLASS__ . ' enum'];
	}
}

var_dump(Foo::Bar);

?>
</PHP>

produces the output

<code>
enum(Foo::Bar) (1) {
  [0]=>
  string(29) "Bar is a case of the Foo enum"
}
</code>

Simple example for a backed enum:
<PHP>
<?php

enum Foo: string {
	case Bar = "Baz";

	public function __debugInfo() {
		return [__CLASS__ . '::' . $this->name . ' = ' . $this->value];
	}
}

var_dump(Foo::Bar);

?>
</PHP>

produces the output

<code>
enum(Foo::Bar) (1) {
  [0]=>
  string(14) "Foo::Bar = Baz"
}
</code>


===== Backward Incompatible Changes =====
There should be no backward incompatible changes - this is the removal of an existing error.

===== Proposed PHP Version(s) =====
Next PHP version (PHP 8.6).

===== RFC Impact =====
==== To the Ecosystem ====
Analysis tools that warn about trying to define a <php>__debugInfo()</php> method on enums would need to be updated to not warn when the code is for PHP 8.6+.

==== To Existing Extensions ====
There are some built-in enums, e.g. <php>\Random\IntervalBoundary</php> - in the future, they may have <php>__debugInfo()</php> methods, but this RFC does not include such additions.

===== Future Scope =====
Perhaps some of the other magic methods should also be allowed.

===== Voting Choices =====

Primary Vote requiring a 2/3 majority to accept the RFC: 

<doodle title="Allow __debugInfo() in enums?" voteType="single" closed="false" closeon="2026-04-16T23:59:59Z">
   * Yes
   * No
   * Abstain
</doodle>

===== Patches and Tests =====

===== Implementation =====

https://github.com/php/php-src/pull/21425

After the RFC is implemented, this section should contain:
  - the version(s) it was merged into
  - a link to the git commit(s)
  - a link to the PHP manual entry for the feature

===== References =====
Links to external references, discussions, or RFCs.

===== Rejected Features =====

  * Originally, an RFC proposed allowing <php>__toString()</php> on enums, rather than <php>__debugInfo()</php>, but feedback on the mailing list (https://news-web.php.net/php.internals/129540) led to a rewrite.

===== Changelog =====
If there are major changes to the initial proposal, please include a short summary with a date or a link to the mailing list announcement here, as not everyone has access to the wikis' version history.

  * v0.2: created (started from v0.2 since the <php>__toString()</php> version could be considered v0.1)
  * v0.3: updated implementation to keep the <php>enum(Foo::Bar)</php> headers in the output, updated examples here to show the full output, minor editorial changes