Refactor Language variables section basics (#3838)

* Fix grammar

* Lack of axiom. Label is not a defined word in this context.

* Inline the note for less confusion

* Add a note on Unicode support in variable names

* Move the see also to the bottom of the page

* Clarify that variable name can be anything

* Remove "named" variable and clarify that a function may return a reference too.

* Rework the bit about undefined variables

* Give examples their titles

* whitespace fixup

* Apply suggestions from code review

Co-authored-by: Christoph M. Becker <[email protected]>

* Fix grammar

* Remove <para> tags around examples

* Suggestions from review

* Remove <para>

* Use simpara

* Use <screen>

---------

Co-authored-by: Christoph M. Becker <[email protected]>

Author: kamil-tekiela

language/variables.xml

@@ -12,17 +12,20 @@
    </simpara>
 
    <para>
-    Variable names follow the same rules as other labels in PHP. A
-    valid variable name starts with a letter or underscore, followed
+    A valid variable name starts with a letter
+    (<literal>A-Z</literal>, <literal>a-z</literal>, or the bytes from 128 through 255)
+    or underscore, followed
     by any number of letters, numbers, or underscores. As a regular
     expression, it would be expressed thus:
     <code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>
    </para>
-   
+
    <note>
     <simpara>
-     For our purposes here, a letter is a-z, A-Z, and the bytes
-     from 128 through 255 (<literal>0x80-0xff</literal>).
+     PHP doesn't support Unicode variable names, however, some character
+     encodings (such as UTF-8) encode characters in such a way that all bytes
+     of a multi-byte character fall within the allowed range, thus making it a
+     valid variable name.
     </simpara>
    </note>
 
@@ -38,14 +41,9 @@
 
    &tip.userlandnaming;
 
-   <para>
-    For information on variable related functions, see the
-    <link linkend="ref.var">Variable Functions Reference</link>.
-   </para>
-
-   <para>
-    <informalexample>
-     <programlisting role="php"> 
+   <example>
+    <title>Valid and invalid variable names</title>
+    <programlisting role="php">
 <![CDATA[
 <?php
 $var = 'Bob';
@@ -57,9 +55,35 @@ $_4site = 'not yet';    // valid; starts with an underscore
 $täyte = 'mansikka';    // valid; 'ä' is (Extended) ASCII 228.
 ?>
 ]]>
-     </programlisting>
-    </informalexample>
-   </para>
+    </programlisting>
+   </example>
+
+   <simpara>
+    PHP accepts a sequence of any bytes as a variable name. Variable
+    names that do not follow the above-mentioned naming rules can only be
+    accessed dynamically at runtime. See
+    <link linkend="language.variables.variable">variable variables</link>
+    for information on how to access them.
+   </simpara>
+
+   <example>
+    <title>Accessing obscure variable names</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+${'invalid-name'} = 'bar';
+$name = 'invalid-name';
+echo ${'invalid-name'}, " ", $$name;
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen>
+<![CDATA[
+bar bar
+]]>
+    </screen>
+   </example>
 
    <para>
     By default, variables are always assigned by value. That is to say,
@@ -100,7 +124,7 @@ echo $foo;                 // $foo is altered too.
    </para>
 
    <para>
-    One important thing to note is that only named variables may be
+    One important thing to note is that only variables may be
     assigned by reference.
     <informalexample>
      <programlisting role="php">
@@ -115,66 +139,71 @@ function test()
    return 25;
 }
 
-$bar = &test();    // Invalid.
+$bar = &test();    // Invalid because test() doesn't return a variable by reference.
 ?>
 ]]>
      </programlisting>
     </informalexample>
    </para>
 
    <para>
-    It is not necessary to initialize variables in PHP however it is a very
-    good practice. Uninitialized variables have a default value of their type depending on the context in which they are used
-    - booleans default to &false;, integers and floats default to zero, strings (e.g. used in <function>echo</function>) are 
-    set as an empty string and arrays become to an empty array.
+    It is not necessary to declare variables in PHP, however, it is a very
+    good practice. Accessing an undefined variable will result in an
+    <constant>E_WARNING</constant> (prior to PHP 8.0.0, <constant>E_NOTICE</constant>).
+    An undefined variable has a default value of &null;.
+    The <function>isset</function> language
+    construct can be used to detect if a variable has already been initialized.
    </para>
    <para>
     <example>
-     <title>Default values of uninitialized variables</title>
+     <title>Default value of an uninitialized variable</title>
      <programlisting role="php">
 <![CDATA[
 <?php
-// Unset AND unreferenced (no use context) variable; outputs NULL
+// Unset AND unreferenced (no use context) variable.
 var_dump($unset_var);
-
-// Boolean usage; outputs 'false' (See ternary operators for more on this syntax)
-echo $unset_bool ? "true\n" : "false\n";
-
-// String usage; outputs 'string(3) "abc"'
-$unset_str .= 'abc';
-var_dump($unset_str);
-
-// Integer usage; outputs 'int(25)'
-$unset_int += 25; // 0 + 25 => 25
-var_dump($unset_int);
-
-// Float usage; outputs 'float(1.25)'
-$unset_float += 1.25;
-var_dump($unset_float);
-
-// Array usage; outputs array(1) {  [3]=>  string(3) "def" }
-$unset_arr[3] = "def"; // array() + array(3 => "def") => array(3 => "def")
-var_dump($unset_arr);
-
-// Object usage; creates new stdClass object (see http://www.php.net/manual/en/reserved.classes.php)
-// Outputs: object(stdClass)#1 (1) {  ["foo"]=>  string(3) "bar" }
-$unset_obj->foo = 'bar';
-var_dump($unset_obj);
 ?>
 ]]>
      </programlisting>
+     &example.outputs;
+     <screen>
+<![CDATA[
+Warning: Undefined variable $unset_var in ...
+NULL
+]]>
+     </screen>
     </example>
    </para>
-   <para>
-    Relying on the default value of an uninitialized variable is problematic
-    in the case of including one file into another which uses the same
-    variable name.
-    <constant>E_WARNING</constant> (prior to PHP 8.0.0, <constant>E_NOTICE</constant>)
-    level error is issued in case of
-    working with uninitialized variables, however not in the case of appending
-    elements to the uninitialized array. <function>isset</function> language
-    construct can be used to detect if a variable has been already initialized.
-   </para>
+
+   <simpara>
+    PHP allows array autovivification (automatic creation of new arrays)
+    from an undefined variable.
+    Appending an element to an undefined variable will create a new array and
+    will not generate a warning.
+   </simpara>
+   <example>
+    <title>Autovivification of an array from an undefined variable</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$unset_array[] = 'value'; // Does not generate a warning.
+?>
+]]>
+    </programlisting>
+   </example>
+
+   <warning>
+    <simpara>
+     Relying on the default value of an uninitialized variable is problematic
+     when including one file in another which uses the same
+     variable name.
+    </simpara>
+   </warning>
+
+   <simpara>
+    For information on variable-related functions, see the
+    <link linkend="ref.var">Variable Functions Reference</link>.
+   </simpara>
   </sect1>
 
   <sect1 xml:id="language.variables.predefined">