Debugable Enums View as Markdown

Introduction

Enumerations (enums) were introduced in PHP 8.1 (enumerations). The RFC specified that magic methods other than __call(), __callStatic(), and __invoke() 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 __debugInfo(), which does not need to involve state. This RFC proposes allowing the __debugInfo() magic method on enums.

<?php
 
enum Foo: string {
	case Bar = "Baz";
 
	public function __debugInfo() {
		return [__CLASS__ . '::' . $this->name . ' = ' . $this->value];
	}
}
 
var_dump(Foo::Bar);
 
?>

produces the output

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

Proposal

The error when trying to implement __debugInfo() 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
 
enum Foo {
	case Bar;
 
	public function __debugInfo() {
		return [$this->name . ' is a case of the ' . __CLASS__ . ' enum'];
	}
}
 
var_dump(Foo::Bar);
 
?>

produces the output

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

Simple example for a backed enum:

<?php
 
enum Foo: string {
	case Bar = "Baz";
 
	public function __debugInfo() {
		return [__CLASS__ . '::' . $this->name . ' = ' . $this->value];
	}
}
 
var_dump(Foo::Bar);
 
?>

produces the output

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

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 __debugInfo() 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. \Random\IntervalBoundary - in the future, they may have __debugInfo() 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:

Vote: Allow __debugInfo() in enums? — Yes: 16 · No: 2 · Abstain: 5 (closed)

Patches and Tests

Implementation

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

After the RFC is implemented, this section should contain:

1. the version(s) it was merged into
2. a link to the git commit(s)
3. 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 __toString() on enums, rather than __debugInfo(), 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 __toString() version could be considered v0.1)
• v0.3: updated implementation to keep the enum(Foo::Bar) headers in the output, updated examples here to show the full output, minor editorial changes