Table of Contents

PHP RFC: Debugable Enums

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:

Allow __debugInfo() in enums?
Real name Yes No Abstain
beberlei   
bwoebi   
daniels   
ilutov   
kalle   
ocramius   
pmjones   
timwolla   
Count: 4 2 2
This poll will close on 2026-04-16 23:59:59 UTC.

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

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.