[DOC-CVS] [doc-en] master: WASM: Enable runnable examples for language sections: attributes, generators and references (#5484)

Author: AllenJB (AllenJB)
Committer: GitHub (web-flow)
Pusher: jordikroon
Date: 2026-05-07T20:19:58+02:00

Commit: https://github.com/php/doc-en/commit/50e6f42c83ac3f6de5e1086b649e06adedd562ff
Raw diff: https://github.com/php/doc-en/commit/50e6f42c83ac3f6de5e1086b649e06adedd562ff.diff

WASM: Enable runnable examples for language sections: attributes, generators and references (#5484)

* Enable runnable (WASM) examples for language.generators and language.attributes sections

Co-authored-by: Louis-Arnaud <[email protected]>

Changed paths:
  M  language/attributes.xml
  M  language/generators.xml
  M  language/references.xml


Diff:

diff --git a/language/attributes.xml b/language/attributes.xml
index ced697417d32..81f1796c71b3 100644
--- a/language/attributes.xml
+++ b/language/attributes.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
- <chapter xml:id="language.attributes" xmlns="http://docbook.org/ns/docbook">
+ <chapter xml:id="language.attributes" xmlns="http://docbook.org/ns/docbook" annotations="interactive">
   <title>Attributes</title>
   <sect1 xml:id="language.attributes.overview">
    <title>Attributes overview</title>
@@ -30,7 +30,7 @@
 
    <example>
     <title>Implementing optional methods of an interface with Attributes</title>
-     <programlisting role="php">
+     <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
 interface ActionHandler
@@ -121,7 +121,7 @@ executeAction($copyAction);
    <example>
     <title>Attribute Syntax</title>
 
-    <programlisting role="php">
+    <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
 // a.php
@@ -222,7 +222,11 @@ function dumpAttributeData($reflection) {
 }
 
 dumpAttributeData(new ReflectionClass(Thing::class));
-/*
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
 string(11) "MyAttribute"
 array(1) {
   ["value"]=>
@@ -232,10 +236,8 @@ object(MyAttribute)#3 (1) {
   ["value"]=>
   int(1234)
 }
-*/
-
 ]]>
-    </programlisting>
+    </screen>
    </example>
 
    <para>
@@ -250,6 +252,21 @@ object(MyAttribute)#3 (1) {
     <programlisting role="php">
 <![CDATA[
 <?php
+#[Attribute]
+class MyAttribute
+{
+    public $value;
+
+    public function __construct($value)
+    {
+        $this->value = $value;
+    }
+}
+
+#[MyAttribute(value: 1234)]
+class Thing
+{
+}
 
 function dumpMyAttributeData($reflection) {
     $attributes = $reflection->getAttributes(MyAttribute::class);
@@ -280,7 +297,7 @@ dumpMyAttributeData(new ReflectionClass(Thing::class));
   <example>
    <title>Simple Attribute Class</title>
 
-   <programlisting role="php">
+   <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
 
@@ -305,7 +322,7 @@ class MyAttribute
   <example>
    <title>Using target specification to restrict where attributes can be used</title>
 
-   <programlisting role="php">
+   <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
 
@@ -348,7 +365,7 @@ class MyAttribute
    <example>
     <title>Using IS_REPEATABLE to allow attribute on a declaration multiple times</title>
 
-    <programlisting role="php">
+    <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
 
diff --git a/language/generators.xml b/language/generators.xml
index 06e6bbf2f709..ad41e84e6dea 100644
--- a/language/generators.xml
+++ b/language/generators.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<chapter xml:id="language.generators" xmlns="http://docbook.org/ns/docbook">
+<chapter xml:id="language.generators" xmlns="http://docbook.org/ns/docbook" annotations="interactive">
  <title>Generators</title>
 
  <sect1 xml:id="language.generators.overview">
@@ -84,7 +84,6 @@ echo 'Single digit odd numbers from xrange(): ';
 foreach (xrange(1, 9, 2) as $number) {
     echo "$number ";
 }
-?>
 ]]>
    </programlisting>
    &example.outputs;
@@ -166,7 +165,6 @@ $generator = gen_one_to_three();
 foreach ($generator as $value) {
     echo "$value\n";
 }
-?>
 ]]>
     </programlisting>
     &example.outputs;
@@ -230,7 +228,6 @@ foreach (input_parser($input) as $id => $fields) {
     echo "    $fields[0]\n";
     echo "    $fields[1]\n";
 }
-?>
 ]]>
      </programlisting>
      &example.outputs;
@@ -270,7 +267,6 @@ function gen_three_nulls() {
 }
 
 var_dump(iterator_to_array(gen_three_nulls()));
-?>
 ]]>
      </programlisting>
      &example.outputs;
@@ -320,7 +316,6 @@ function &gen_reference() {
 foreach (gen_reference() as &$number) {
     echo (--$number).'... ';
 }
-?>
 ]]>
      </programlisting>
      &example.outputs;
@@ -386,7 +381,6 @@ function gen() {
 }
 // pass false as second parameter to get an array [0, 1, 2, 3, 4]
 var_dump(iterator_to_array(gen()));
-?>
 ]]>
        </programlisting>
        &example.outputs;
@@ -432,7 +426,6 @@ function eight() {
 foreach (count_to_ten() as $num) {
     echo "$num ";
 }
-?>
 ]]>
      </programlisting>
      &example.outputs;
@@ -476,7 +469,6 @@ foreach ($gen as $num) {
     echo "$num ";
 }
 echo $gen->getReturn();
-?>
 ]]>
      </programlisting>
      &example.outputs;
@@ -501,7 +493,7 @@ echo $gen->getReturn();
   </para>
 
   <informalexample>
-   <programlisting role="php">
+   <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
 function getLinesFromFile($fileName) {
@@ -559,7 +551,6 @@ class LineIterator implements Iterator {
         fclose($this->fileHandle);
     }
 }
-?>
 ]]>
    </programlisting>
   </informalexample>
diff --git a/language/references.xml b/language/references.xml
index 7eafdfacfcdb..106ee01df022 100644
--- a/language/references.xml
+++ b/language/references.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
- <chapter xml:id="language.references" xmlns="http://docbook.org/ns/docbook">
+ <chapter xml:id="language.references" xmlns="http://docbook.org/ns/docbook" annotations="interactive">
   <title>References Explained</title>
   
   <sect1 xml:id="language.references.whatare">
@@ -38,13 +38,10 @@
      In the first of these, PHP references allow you to make two
      variables refer to the same content. Meaning, when you do:
      <informalexample>
-      <programlisting role="php">
+      <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
-
 $a =& $b;
-
-?>
 ]]>
       </programlisting>
      </informalexample>
@@ -81,8 +78,6 @@ var_dump(array_key_exists('b', $b)); // bool(true)
 $c = new stdClass();
 foo($c->d);
 var_dump(property_exists($c, 'd')); // bool(true)
-
-?>
 ]]>
        </programlisting>
       </example>
@@ -92,13 +87,10 @@ var_dump(property_exists($c, 'd')); // bool(true)
      The same syntax can be used with functions that return
      references:
      <informalexample>
-      <programlisting role="php">
+      <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
-
 $foo =& find_var($bar);
-
-?>
 ]]>
       </programlisting>
      </informalexample>
@@ -120,7 +112,6 @@ $foo =& find_var($bar);
        <programlisting role="php">
 <![CDATA[
 <?php
-
 $var1 = "Example variable";
 $var2 = "";
 
@@ -140,8 +131,6 @@ echo "var2 is set to '$var2'\n"; // var2 is set to ''
 
 global_references(true);
 echo "var2 is set to '$var2'\n"; // var2 is set to 'Example variable'
-
-?>
 ]]>
        </programlisting>
       </example>
@@ -159,7 +148,6 @@ echo "var2 is set to '$var2'\n"; // var2 is set to 'Example variable'
        <programlisting role="php">
 <![CDATA[
 <?php
-
 $ref = 0;
 $row =& $ref;
 
@@ -168,8 +156,6 @@ foreach (array(1, 2, 3) as $row) {
 }
 
 echo $ref; // 3 - last element of the iterated array
-
-?>
 ]]>
        </programlisting>
       </example>
@@ -185,7 +171,6 @@ echo $ref; // 3 - last element of the iterated array
       <programlisting role="php">
 <![CDATA[
 <?php
-
 $a = 1;
 $b = array(2, 3);
 
@@ -194,8 +179,8 @@ $arr[0]++;
 $arr[1]++;
 $arr[2]++;
 /* $a == 2, $b == array(3, 4); */
-
-?>
+var_dump($a);
+var_dump($b);
 ]]>
       </programlisting>
      </informalexample>
@@ -216,6 +201,7 @@ $a = 1;
 $b =& $a;
 $c = $b;
 $c = 7; // $c is not a reference; no change to $a or $b
+print "a = {$a}; b = {$b}; c = {$c}\n\n";
 
 /* Assignment of array variables */
 $arr = array(1);
@@ -224,8 +210,9 @@ $arr2 = $arr; // Not an assignment-by-reference!
 $arr2[0]++;
 /* $a == 2, $arr == array(2) */
 /* The contents of $arr are changed even though it's not a reference! */
-
-?>
+print "a = {$a}\n";
+var_dump($arr);
+var_dump($arr2);
 ]]>
       </programlisting>
      </informalexample>
@@ -245,16 +232,14 @@ $arr2[0]++;
       <programlisting role="php">
 <![CDATA[
 <?php
-
 function foo(&$var)
 {
     $var++;
 }
 
-$a=5;
+$a = 5;
 foo($a);
-
-?>
+print $a;
 ]]>
       </programlisting>
      </informalexample>
@@ -281,18 +266,15 @@ foo($a);
     As said before, references are not pointers. That means, the
     following construct won't do what you expect:
     <informalexample>
-     <programlisting role="php">
+     <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
-
 function foo(&$var)
 {
     $var =& $GLOBALS["baz"];
 }
 
 foo($bar);
-
-?>
 ]]>
      </programlisting>
     </informalexample>
@@ -322,18 +304,14 @@ foo($bar);
      <programlisting role="php">
 <![CDATA[
 <?php
-
 function foo(&$var)
 {
     $var++;
 }
 
-$a=5;
-
+$a = 5;
 foo($a);
-// $a is 6 here
-
-?>
+print $a; // $a is 6 here
 ]]>
      </programlisting>
     </informalexample>
@@ -364,6 +342,7 @@ foo($a);
 function foo(&$var)
 {
     $var++;
+    print $var;
 }
 
 function &bar()
@@ -373,8 +352,6 @@ function &bar()
 }
 
 foo(bar());
-
-?>
 ]]>
      </programlisting>
     </informalexample>
@@ -389,7 +366,7 @@ foo(bar());
   result is undefined. For example, the following examples of passing
   by reference are invalid:
     <informalexample>
-     <programlisting role="php">
+     <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
 
@@ -413,8 +390,6 @@ class Foobar {}
 
 foo(new Foobar()) // Produces a notice as of PHP 7.0.7
                   // Notice: Only variables should be passed by reference
-
-?>
 ]]>
      </programlisting>
     </informalexample>
@@ -449,8 +424,6 @@ $obj = new Foo();
 $myValue = &$obj->getValue(); // $myValue is a reference to $obj->value, which is 42
 $obj->value = 2;
 echo $myValue;                // Prints the new value of $obj->value, i.e. 2
-
-?> 
 ]]>
      </programlisting>
     </informalexample>
@@ -495,14 +468,17 @@ $collection = &collector();
 $collection[] = 'foo';
 
 print_r(collector());
-// Array
-// (
-//    [0] => foo
-// )
-
-?> 
 ]]>
      </programlisting>
+     &example.outputs;
+     <screen>
+<![CDATA[
+Array
+(
+    [0] => foo
+)
+]]>
+     </screen>
     </informalexample>
    <note>
     <simpara>
@@ -513,7 +489,7 @@ print_r(collector());
    To pass the returned reference to another function expecting a reference
    you can use this syntax:
     <informalexample>
-     <programlisting role="php">
+     <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
 
@@ -524,8 +500,6 @@ function &collector()
 }
 
 array_push(collector(), 'foo');
-
-?> 
 ]]>
      </programlisting>
     </informalexample>
@@ -552,8 +526,8 @@ array_push(collector(), 'foo');
 $a = 1;
 $b =& $a;
 unset($a); 
-
-?>
+var_dump($a);
+var_dump($b);
 ]]>
      </programlisting>
     </informalexample>
@@ -582,13 +556,10 @@ unset($a);
      are in fact creating reference to a global variable. That means,
      this is the same as:
      <informalexample>
-      <programlisting role="php">
+      <programlisting role="php" annotations="non-interactive">
 <![CDATA[
 <?php
-
 $var =& $GLOBALS["var"];
-
-?>
 ]]>
       </programlisting>
      </informalexample>