[DOC-CVS] [doc-en] master: WASM: Enable runnable examples for language.enumerations section (#5479)
[email protected] (AllenJB via GitHub) Wed, 6 May 2026 16:54:49 +0000
| Newsgroups | php.doc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: AllenJB (AllenJB)
Committer: GitHub (web-flow)
Pusher: jordikroon
Date: 2026-05-06T18:54:46+02:00
Commit: https://github.com/php/doc-en/commit/1eb67bea30f61f7d9cdfd371146911a0ba07bbd2
Raw diff: https://github.com/php/doc-en/commit/1eb67bea30f61f7d9cdfd371146911a0ba07bbd2.diff
WASM: Enable runnable examples for language.enumerations section (#5479)
Changed paths:
M language/enumerations.xml
Diff:
diff --git a/language/enumerations.xml b/language/enumerations.xml
index 20c33ce40892..997897015312 100644
--- a/language/enumerations.xml
+++ b/language/enumerations.xml
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
- <chapter xml:id="language.enumerations" xmlns="http://docbook.org/ns/docbook">
+ <chapter xml:id="language.enumerations" xmlns="http://docbook.org/ns/docbook" annotations="interactive">
<title>Enumerations</title>
<sect1 xml:id="language.enumerations.overview">
<title>Enumerations overview</title>
@@ -34,10 +34,9 @@
</para>
- <programlisting role="php">
+ <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
-
enum Suit
{
case Hearts;
@@ -45,7 +44,6 @@ enum Suit
case Clubs;
case Spades;
}
-?>
]]>
</programlisting>
@@ -57,13 +55,21 @@ enum Suit
in which case only values of that type may be passed.
</para>
- <programlisting role="php">
+ <informalexample>
+ <programlisting role="php">
<![CDATA[
<?php
+enum Suit
+{
+ case Hearts;
+ case Diamonds;
+ case Clubs;
+ case Spades;
+}
function pick_a_card(Suit $suit)
{
- /* ... */
+ var_dump($suit);
}
$val = Suit::Diamonds;
@@ -76,9 +82,9 @@ pick_a_card(Suit::Clubs);
// TypeError: pick_a_card(): Argument #1 ($suit) must be of type Suit, string given
pick_a_card('Spades');
-?>
]]>
- </programlisting>
+ </programlisting>
+ </informalexample>
<para>
An Enumeration may have zero or more <literal>case</literal> definitions, with no maximum.
@@ -95,21 +101,35 @@ pick_a_card('Spades');
is not equal to <literal>"0"</literal>. Instead, each case is backed by a singleton object of that name. That means that:
</para>
- <programlisting role="php">
+ <informalexample>
+ <programlisting role="php">
<![CDATA[
<?php
+enum Suit
+{
+ case Hearts;
+ case Diamonds;
+ case Clubs;
+ case Spades;
+}
$a = Suit::Spades;
$b = Suit::Spades;
-$a === $b; // true
+if ($a === $b) {
+ print "Suits match using ===\n";
+}
-$a instanceof Suit; // true
+if ($a instanceof Suit) {
+ print "Suits match using instanceof\n";
+}
-$a !== 'Spades'; // true
-?>
+if ($a !== 'Spades') {
+ print "Suit does not match the string\n";
+}
]]>
- </programlisting>
+ </programlisting>
+ </informalexample>
<para>
It also means that enum values are never <literal><</literal> or <literal>></literal> each other,
@@ -131,15 +151,23 @@ $a !== 'Spades'; // true
of the case itself.
</para>
- <programlisting role="php">
+ <informalexample>
+ <programlisting role="php">
<![CDATA[
<?php
+enum Suit
+{
+ case Hearts;
+ case Diamonds;
+ case Clubs;
+ case Spades;
+}
print Suit::Spades->name;
// prints "Spades"
-?>
]]>
- </programlisting>
+ </programlisting>
+ </informalexample>
<para>
It is also possible to use the <function>defined</function> and <function>constant</function>
@@ -162,10 +190,9 @@ print Suit::Spades->name;
<para>To define a scalar equivalent for an Enumeration, the syntax is as follows:</para>
- <programlisting role="php">
+ <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
-
enum Suit: string
{
case Hearts = 'H';
@@ -173,7 +200,6 @@ enum Suit: string
case Clubs = 'C';
case Spades = 'S';
}
-?>
]]>
</programlisting>
@@ -205,31 +231,47 @@ enum Suit: string
specified in the definition.
</para>
- <programlisting role="php">
+ <informalexample>
+ <programlisting role="php">
<![CDATA[
<?php
+enum Suit: string
+{
+ case Hearts = 'H';
+ case Diamonds = 'D';
+ case Clubs = 'C';
+ case Spades = 'S';
+}
print Suit::Clubs->value;
// Prints "C"
-?>
]]>
- </programlisting>
+ </programlisting>
+ </informalexample>
<para>
In order to enforce the <literal>value</literal> property as read-only, a variable cannot
be assigned as a reference to it. That is, the following throws an error:
</para>
- <programlisting role="php">
+ <informalexample>
+ <programlisting role="php">
<![CDATA[
<?php
+enum Suit: string
+{
+ case Hearts = 'H';
+ case Diamonds = 'D';
+ case Clubs = 'C';
+ case Spades = 'S';
+}
$suit = Suit::Clubs;
$ref = &$suit->value;
-// Error: Cannot acquire reference to property Suit::$value
-?>
+// Fatal Error: Cannot indirectly modify readonly property Suit::$value
]]>
- </programlisting>
+ </programlisting>
+ </informalexample>
<para>
Backed enums implement an internal <interfacename>BackedEnum</interfacename> interface,
@@ -261,23 +303,37 @@ $ref = &$suit->value;
in both modes.
</para>
- <programlisting role="php">
+ <informalexample>
+ <programlisting role="php">
<![CDATA[
<?php
+enum Suit: string
+{
+ case Hearts = 'H';
+ case Diamonds = 'D';
+ case Clubs = 'C';
+ case Spades = 'S';
+}
-$record = get_stuff_from_database($id);
-print $record['suit'];
+function get_stuff_from_database($id) {
+ return [
+ 'suit' => 'S',
+ ];
+}
-$suit = Suit::from($record['suit']);
-// Invalid data throws a ValueError: "X" is not a valid scalar value for enum "Suit"
-print $suit->value;
+$record = get_stuff_from_database(42);
+print $record['suit'] . "\n";
$suit = Suit::tryFrom('A') ?? Suit::Spades;
// Invalid data returns null, so Suit::Spades is used instead.
-print $suit->value;
-?>
+print $suit->value . "\n";
+
+$suit = Suit::from('X');
+// Invalid data throws a ValueError: "X" is not a valid backing scalar value for enum Suit
+print $suit->value . "\n";
]]>
- </programlisting>
+ </programlisting>
+ </informalexample>
<para>Manually defining a <literal>from()</literal> or <literal>tryFrom()</literal> method on a Backed Enum will result in a fatal error.</para>
@@ -292,10 +348,10 @@ print $suit->value;
all cases of that Enum.
</para>
- <programlisting role="php">
+ <informalexample>
+ <programlisting role="php">
<![CDATA[
<?php
-
interface Colorful
{
public function color(): string;
@@ -326,15 +382,15 @@ enum Suit implements Colorful
function paint(Colorful $c)
{
- /* ... */
+ print $c->color() . "\n";
}
paint(Suit::Clubs); // Works
print Suit::Diamonds->shape(); // prints "Rectangle"
-?>
]]>
- </programlisting>
+ </programlisting>
+ </informalexample>
<para>
In this example, all four instances of <literal>Suit</literal> have two methods,
@@ -346,10 +402,9 @@ print Suit::Diamonds->shape(); // prints "Rectangle"
On a Backed Enum, the interface declaration goes after the backing type declaration.
</para>
- <programlisting role="php">
+ <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
-
interface Colorful
{
public function color(): string;
@@ -371,7 +426,6 @@ enum Suit: string implements Colorful
};
}
}
-?>
]]>
</programlisting>
@@ -396,10 +450,9 @@ enum Suit: string implements Colorful
(although this is not the actual code that runs):
</para>
- <programlisting role="php">
+ <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
-
interface Colorful
{
public function color(): string;
@@ -433,7 +486,6 @@ final class Suit implements UnitEnum, Colorful
// See also "Value listing" section.
}
}
-?>
]]>
</programlisting>
@@ -452,10 +504,10 @@ final class Suit implements UnitEnum, Colorful
enumeration itself is primarily for alternative constructors. E.g.:
</para>
- <programlisting role="php">
+ <informalexample>
+ <programlisting role="php">
<![CDATA[
<?php
-
enum Size
{
case Small;
@@ -471,9 +523,11 @@ enum Size
};
}
}
-?>
+
+var_dump(Size::fromLength(50));
]]>
- </programlisting>
+ </programlisting>
+ </informalexample>
<para>
Static methods may be public, private, or protected, although in practice private
@@ -492,10 +546,10 @@ enum Size
<para>An enum constant may refer to an enum case:</para>
- <programlisting role="php">
+ <informalexample>
+ <programlisting role="php">
<![CDATA[
<?php
-
enum Size
{
case Small;
@@ -504,9 +558,11 @@ enum Size
public const Huge = self::Large;
}
-?>
+
+var_dump(Size::Huge);
]]>
- </programlisting>
+ </programlisting>
+ </informalexample>
</sect1>
<sect1 xml:id="language.enumerations.traits">
@@ -518,10 +574,10 @@ enum Size
result in a fatal error.
</para>
- <programlisting role="php">
+ <informalexample>
+ <programlisting role="php">
<![CDATA[
<?php
-
interface Colorful
{
public function color(): string;
@@ -551,9 +607,13 @@ enum Suit implements Colorful
};
}
}
-?>
+
+$suit = Suit::Spades;
+var_dump($suit->color());
+var_dump($suit->shape());
]]>
- </programlisting>
+ </programlisting>
+ </informalexample>
</sect1>
<sect1 xml:id="language.enumerations.expressions">
@@ -573,10 +633,9 @@ enum Suit implements Colorful
property access continue to be invalid operations in constant expressions.
</para>
- <programlisting role="php">
+ <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
-
// This is an entirely legal Enum definition.
enum Direction implements ArrayAccess
{
@@ -619,7 +678,6 @@ $x = Direction::Up['short'];
var_dump("\$x is " . var_export($x, true));
$foo = new Foo();
-?>
]]>
</programlisting>
</sect1>
@@ -673,16 +731,14 @@ $foo = new Foo();
<methodname>ReflectionClass::newInstanceWithoutConstructor</methodname> in reflection. Both will result in an error.
</para>
- <programlisting role="php">
+ <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
-
$clovers = new Suit();
// Error: Cannot instantiate enum Suit
$horseshoes = (new ReflectionClass(Suit::class))->newInstanceWithoutConstructor()
// Error: Cannot instantiate enum Suit
-?>
]]>
</programlisting>
</sect1>
@@ -697,15 +753,32 @@ $horseshoes = (new ReflectionClass(Suit::class))->newInstanceWithoutConstructor(
all defined Cases in the order of declaration.
</para>
- <programlisting role="php">
+ <informalexample>
+ <programlisting role="php">
<![CDATA[
<?php
+enum Suit
+{
+ case Hearts;
+ case Diamonds;
+ case Clubs;
+ case Spades;
+}
-Suit::cases();
-// Produces: [Suit::Hearts, Suit::Diamonds, Suit::Clubs, Suit::Spades]
-?>
+var_dump(Suit::cases());
+
+enum SuitBacked: string
+{
+ case Hearts = 'H';
+ case Diamonds = 'D';
+ case Clubs = 'C';
+ case Spades = 'S';
+}
+
+var_dump(SuitBacked::cases());
]]>
- </programlisting>
+ </programlisting>
+ </informalexample>
<para>Manually defining a <literal>cases()</literal> method on an Enum will result in a fatal error.</para>
</sect1>
@@ -719,17 +792,25 @@ Suit::cases();
able to use that to set a variable to the existing singleton value. That ensures that:
</para>
- <programlisting role="php">
+ <informalexample>
+ <programlisting role="php">
<![CDATA[
<?php
+enum Suit: string
+{
+ case Hearts = 'H';
+ case Diamonds = 'D';
+ case Clubs = 'C';
+ case Spades = 'S';
+}
Suit::Hearts === unserialize(serialize(Suit::Hearts));
print serialize(Suit::Hearts);
// E:11:"Suit:Hearts";
-?>
]]>
- </programlisting>
+ </programlisting>
+ </informalexample>
<para>
On deserialization, if an enum and case cannot be found to match a serialized
@@ -746,10 +827,10 @@ print serialize(Suit::Hearts);
from objects to minimize confusion.
</para>
- <programlisting role="php">
+ <informalexample>
+ <programlisting role="php">
<![CDATA[
<?php
-
enum Foo {
case Bar;
}
@@ -771,9 +852,9 @@ Baz Enum:int {
[value] => 5
}
*/
-?>
]]>
- </programlisting>
+ </programlisting>
+ </informalexample>
</sect1>
<sect1 xml:id="language.enumerations.object-differences.inheritance">
@@ -784,10 +865,9 @@ Baz Enum:int {
Classes have contracts on their methods:
</simpara>
- <programlisting role="php">
+ <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
-
class A {}
class B extends A {}
@@ -796,7 +876,6 @@ function foo(A $a) {}
function bar(B $b) {
foo($b);
}
-?>
]]>
</programlisting>
@@ -810,10 +889,9 @@ function bar(B $b) {
Enums have contracts on their cases, not methods:
</simpara>
- <programlisting role="php">
+ <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
-
enum ErrorCode {
case SOMETHING_BROKE;
}
@@ -825,8 +903,6 @@ function quux(ErrorCode $errorCode)
ErrorCode::SOMETHING_BROKE => true,
};
}
-
-?>
]]>
</programlisting>
@@ -840,10 +916,9 @@ function quux(ErrorCode $errorCode)
</simpara>
- <programlisting role="php">
+ <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
-
// Thought experiment code where enums are not final.
// Note, this won't actually work in PHP.
enum MoreErrorCode extends ErrorCode {
@@ -855,10 +930,8 @@ function fot(MoreErrorCode $errorCode) {
}
fot(MoreErrorCode::PEBKAC);
-
-?>
]]>
- </programlisting>
+ </programlisting>
<simpara>
Under normal inheritance rules, a class that extends another will pass
@@ -881,10 +954,9 @@ fot(MoreErrorCode::PEBKAC);
<para>
<example>
<title>Basic limited values</title>
- <programlisting role="php">
+ <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php
-
enum SortOrder
{
case Asc;
@@ -895,7 +967,6 @@ function query($fields, $filter, SortOrder $order = SortOrder::Asc)
{
/* ... */
}
-?>
]]>
</programlisting>
<para>
@@ -915,7 +986,6 @@ function query($fields, $filter, SortOrder $order = SortOrder::Asc)
<programlisting role="php">
<![CDATA[
<?php
-
enum UserStatus: string
{
case Pending = 'P';
@@ -933,7 +1003,9 @@ enum UserStatus: string
};
}
}
-?>
+
+$status = UserStatus::Suspended;
+var_dump($status->label());
]]>
</programlisting>
@@ -953,11 +1025,31 @@ enum UserStatus: string
<programlisting role="php">
<![CDATA[
<?php
+enum UserStatus: string
+{
+ case Pending = 'P';
+ case Active = 'A';
+ case Suspended = 'S';
+ case CanceledByUser = 'C';
+
+ public function label(): string
+ {
+ return match($this) {
+ self::Pending => 'Pending',
+ self::Active => 'Active',
+ self::Suspended => 'Suspended',
+ self::CanceledByUser => 'Canceled by user',
+ };
+ }
+}
foreach (UserStatus::cases() as $case) {
- printf('<option value="%s">%s</option>\n', $case->value, $case->label());
+ printf(
+ "<option value=\"%s\">%s</option>\n",
+ htmlentities($case->value),
+ htmlentities($case->label())
+ );
}
-?>
]]>
</programlisting>
</example>