PHP: rfc:stringable-enums

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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 =====
Keep this updated with features that were discussed on the mail lists.

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