• 5 min read

PHP 8.6 Debugable Enums: Using __debugInfo() on Enum Cases

PHP 8.6 lets enums define __debugInfo(). See the RFC examples, a practical var_dump pattern, and what static analysis tools need to update.

Featured image for "PHP 8.6 Debugable Enums: Using __debugInfo() on Enum Cases"

PHP 8.6 ships on November 19, 2026, and one of its smaller changes fixes an old annoyance. Enums can now define __debugInfo(), so you control what var_dump() shows for a case.

It is a tiny change, since the RFC describes it as the removal of an existing error. But if you use enums with a lot of context attached, it is a nice quality-of-life win. Here is what changed, how to use it, and what to watch for.

Why enums could not do this before

When enums arrived in PHP 8.1, the enumerations RFC banned most magic methods. The reasoning was that most of them deal with state, and enum cases have none. Only __call(), __callStatic(), and __invoke() were allowed.

The Debugable Enums RFC, written by Daniel Scherzer, points out the flaw in that rule. __debugInfo() was caught in the same ban, even though it does not need to involve state. It only decides how an object is presented when you dump it.

What the RFC changes

The RFC removes the error raised when you declare __debugInfo() on an enum. The usual validation for that method still applies, covering visibility, arguments, and return type.

Here is the backed enum example from the RFC:

<?php

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

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

var_dump(Foo::Bar);

The RFC lists this output:

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

Notice the enum(Foo::Bar) header is still there. The RFC’s version 0.3 changelog says the implementation was updated to keep that header in the output. Your custom array shows up beneath it, so you cannot accidentally hide which case you are looking at.

The RFC passed with 16 yes votes, 2 no votes, and 5 abstentions, against a two-thirds threshold. PHP.Watch lists it as implemented for PHP 8.6. The implementation is php-src pull request 21425.

A practical pattern

Where would you actually use this? Think of an enum that carries behavior through methods, like a status with labels and transition rules. A plain dump shows only the case name and value. You may want more context while debugging.

Here is an example using the PHP Architect brand. This is my own illustration, not from the RFC:

<?php

enum TicketStatus: string {
    case Early = 'early';
    case Regular = 'regular';
    case Closed = 'closed';

    public function label(): string
    {
        return match ($this) {
            self::Early => 'Early Bird',
            self::Regular => 'Regular',
            self::Closed => 'Sales Closed',
        };
    }

    public function isOnSale(): bool
    {
        return $this !== self::Closed;
    }

    public function __debugInfo(): array
    {
        return [
            'label' => $this->label(),
            'onSale' => $this->isOnSale(),
        ];
    }
}

var_dump(TicketStatus::Early);

The dump of TicketStatus::Early keeps the enum(TicketStatus::Early) header and then lists the label and onSale entries beneath it. When you are scanning a large dump of a PHPTek registration object, that beats mentally resolving each case.

A few notes on the pattern:

  • Declare the array return type. The RFC says the default validation of the magic method applies, so keep the signature tidy.
  • Keep the method cheap and free of side effects. It runs whenever the value is dumped.
  • Do not put secrets in it. Dumps end up in logs and bug reports.

What to expect from your tools

The RFC lists one ecosystem impact. Static analysis tools that warn about a __debugInfo() method on an enum need updating so they stay quiet for code targeting PHP 8.6 and later. If your CI runs PHPStan, Psalm, or a PHP_CodeSniffer ruleset, check whether your version flags this once you upgrade. I have not tested how each tool handles it, so run your own pipeline against a small test enum before you rely on it.

The RFC also says some built-in enums, such as \Random\IntervalBoundary, might get their own __debugInfo() methods in the future. It does not add any now.

Compatibility and gotchas

There is no backward compatibility break. Code that worked on PHP 8.5 behaves the same on 8.6. The reverse matters more: if you ship a library that supports older versions, a __debugInfo() method in an enum is a compile error on PHP 8.5 and earlier. That is a hard failure, so you cannot ship it in a package that still supports those versions.

If you maintain such a package, keep the method out of shared enums until your minimum version is PHP 8.6. A Composer constraint of "php": ">=8.6" makes the dependency explicit.

The RFC’s future scope section floats the idea that other magic methods might be allowed on enums later. That is only an idea for now, with no proposal attached.

Try it before release

You can test this today with a release candidate build. If you want a ready-made setup, my earlier post on testing PHP 8.6 RC with Docker and GitHub Actions walks through it. Add one enum with __debugInfo() to your test suite, dump it, and confirm the output matches what you expect.

Wrapping up

Debugable enums will not change how you design applications. They do make dumps more useful for enums that carry real behavior, and they remove a rule that never had a strong reason to exist. Plan to use it once your minimum PHP version reaches 8.6.

Sources