====== PHP RFC: Debugable Enums ======
  * Version: 0.2
  * Date: 2026-03-12
  * Author: Daniel Scherzer, daniel.e.scherzer@gmail.com
  * Status: Under Discussion
  * Implementation: https://github.com/php/php-src/pull/21425
  * Discussion thread: 

===== 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); // produces an array with `"Foo::Bar = Baz"`

?>
</PHP>

===== 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); // produces an array with "Bar is a case of the Foo enum"

?>
</PHP>

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); // produces an array with `"Foo::Bar = Baz"`

?>
</PHP>


===== 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 =====

Please consult [[https://github.com/php/policies/blob/main/feature-proposals.rst#voting|the php/policies repository]] for the current voting guidelines.

<doodle title="Allow <php>__debugInfo()</php> in enums" voteType="single" closed="true" closeon="2025-01-01T15:30:00Z">
   * 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.