====== PHP RFC: Stringable Enums ======
  * Version: 0.1
  * Date: 2025-11-07
  * Author: Daniel Scherzer, daniel.e.scherzer@gmail.com
  * Status: Draft (Later in the RFC process "Under Discussion", "Voting", and finally "Accepted", "Declined" or "Implemented")
  * Implementation: https://github.com/php/php-src/pull/20415

===== 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>__toString()</php>, which does not need to involve state. This RFC proposes allowing the <php>__toString()</php> magic method on enums.

<PHP>
<?php

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

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

echo Foo::Bar; // produces "Foo::Bar = Baz"

?>
</PHP>

===== Proposal =====
The error when trying to implement <php>__toString()</php> on an enumeration is removed. The default validation of that magic method (visibility, arguments, return type) is applied if the method is present, and if present the <php>Stringable</php> interface is added as normal ([[rfc:stringable]]).

==== Examples ====

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

enum Foo {
	case Bar;

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

echo Foo::Bar; // produces "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 __toString() {
		return __CLASS__ . '::' . $this->name . ' = ' . $this->value;
	}
}

echo Foo::Bar; // produces "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>__toString()</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>__toString()</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>__toString()</php> in enums" voteType="single" closed="true" closeon="2025-01-01T15:30:00Z">
   * Yes
   * No
   * Abstain
</doodle>

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

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

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

==== Automatic implementation ====

In writing this RFC I was pointed to [[rfc:auto-implement_stringable_for_string_backed_enums]], which proposed that string-backed enums automatically provide <php>__toString()</php> methods that just returned their underlying values. That RFC was eventually withdrawn without a vote, but some concerns raised there are worth addressing. That RFC proposed that

> E.g. defining an enum like this one:
> 
> <code php>
enum Suit: string {
  case Hearts = 'H';
  // ...
}
</code>
> Would virtually define this:
> <code php>
enum Suit: string implements Stringable {
  case Hearts = 'H';
  // ...
  public function __toString(): string
  {
    return $this->value;
  }
}
</code>

However, such automatic implementations assume that the value of a string-backed enum is a good string representation of the object. For the given example of card suits, a better representation might be the name ("Hearts") instead of the value ("H").

That RFC also specified that

> This RFC proposes that string-backed enums auto-implement Stringable, while still disallowing user-land implementations of the method.

Automatic implementations in this manner would thus continue to restrict userland code from specifying desired string representations of enums. While the prohibition on user-land implementations could be removed, the default automatic implementation could be confusing.

Automatic implementation might also result in confusion regarding int-backed enums. After all, if //all// string-backed enums can be cast to strings, why can't int-backed enums be cast to ints? By avoiding the automatic implementation, we align the casting of enums with the casting of objects - you can't cast either to an int, and can only cast them to strings if they implement the <php>__toString()</php> method.

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