Use &true;/&false;/&null; entities for boolean/null constants (#5641)

lacatoire · web-flow · commit 911fe79de766 · 2026-07-09T19:41:57.000+02:00
* Use &amp;true;/&amp;false;/&amp;null; entities for boolean/null constants

Replace &lt;literal&gt;true/false/null&lt;/literal&gt; with the standard entities where they
denote the PHP boolean/null constant. Quoted strings, JSON/INI literals, SQL NULL
and type notations are intentionally left untouched.
diff --git a/language/control-structures/include.xml b/language/control-structures/include.xml
@@ -181,7 +181,7 @@ include 'http://www.example.com/file.php?foo=1&bar=2';
  </para>
  <simpara>
   Handling Returns: <literal>include</literal> returns
-  <literal>FALSE</literal> on failure and raises a warning. Successful
+  &false; on failure and raises a warning. Successful
   includes, unless overridden by the included file, return
   <literal>1</literal>. It is possible to execute a <function>return</function>
   statement inside an included file in order to terminate processing in
diff --git a/language/enumerations.xml b/language/enumerations.xml
@@ -294,7 +294,7 @@ $ref = &$suit->value;
    </member>
    <member>
     <literal>tryFrom(int|string): ?self</literal> will take a scalar and return the
-    corresponding Enum Case. If one is not found, it will return <literal>null</literal>.
+    corresponding Enum Case. If one is not found, it will return &null;.
     This is mainly useful in cases where the input scalar is untrusted and the caller wants
     to implement their own error handling or default-value logic.
    </member>
diff --git a/language/oop5/overloading.xml b/language/oop5/overloading.xml
@@ -116,7 +116,7 @@
     <para>
      PHP will not call an overloaded method from within the same overloaded method.
      That means, for example, writing <code>return $this->foo</code> inside of
-     <link linkend="object.get">__get()</link> will return <literal>null</literal>
+     <link linkend="object.get">__get()</link> will return &null;
      and raise an <constant>E_WARNING</constant> if there is no <literal>foo</literal> property defined,
      rather than calling <link linkend="object.get">__get()</link> a second time.
      However, overload methods may invoke other overload methods implicitly (such as
diff --git a/language/predefined/weakreference.xml b/language/predefined/weakreference.xml
@@ -91,7 +91,7 @@ NULL
        <entry>8.4.0</entry>
        <entry>
         The output of <methodname>WeakReference::__debugInfo</methodname> now includes
-        the referenced object, or <literal>NULL</literal> if the reference is no longer
+        the referenced object, or &null; if the reference is no longer
         valid.
        </entry>
       </row>
diff --git a/language/types/array.xml b/language/types/array.xml
@@ -115,7 +115,7 @@ var_dump($array1, $array2);
      <listitem>
       <simpara>
        <type>Null</type> will be cast to the empty string, i.e. the key
-       <literal>null</literal> will actually be stored under <literal>""</literal>.
+       &null; will actually be stored under <literal>""</literal>.
       </simpara>
      </listitem>
      <listitem>
diff --git a/language/types/declarations.xml b/language/types/declarations.xml
@@ -304,14 +304,14 @@ Stack trace:
     </note>
 
     <note>
-     <para>
+     <simpara>
       It is also possible to achieve nullable arguments by making
-      <literal>null</literal> the default value.
+      &null; the default value.
       This is not recommended as if the default value is changed in a child
       class a type compatibility violation will be raised as the
       <type>null</type> type will need to be added to the type declaration.
       This behavior is also deprecated since PHP 8.4.
-     </para>
+     </simpara>
      <example>
       <title>Old way to make arguments nullable</title>
       <programlisting role="php">
diff --git a/reference/datetime/dateinterval/createfromdatestring.xml b/reference/datetime/dateinterval/createfromdatestring.xml
@@ -89,7 +89,7 @@
       <entry>
        <methodname>DateInterval::createFromDateString</methodname> now throws
        <exceptionname>DateMalformedIntervalStringException</exceptionname> if an
-       invalid string is passed.  Previously, it returned <literal>false</literal>,
+       invalid string is passed.  Previously, it returned &false;,
        and a warning was emitted.
        <function>date_interval_create_from_date_string</function> has not been
        changed.
diff --git a/reference/datetime/datetime/modify.xml b/reference/datetime/datetime/modify.xml
@@ -78,7 +78,7 @@
       <entry>
        <methodname>DateTime::modify</methodname> now throws
        <exceptionname>DateMalformedStringException</exceptionname> if an
-       invalid string is passed.  Previously, it returned <literal>false</literal>,
+       invalid string is passed.  Previously, it returned &false;,
        and a warning was emitted.
        <function>date_modify</function> has not been changed.
       </entry>
diff --git a/reference/datetime/datetimeimmutable/modify.xml b/reference/datetime/datetimeimmutable/modify.xml
@@ -71,7 +71,7 @@
       <entry>
        <methodname>DateTimeImmutable::modify</methodname> now throws
        <exceptionname>DateMalformedStringException</exceptionname> if an
-       invalid string is passed.  Previously, it returned <literal>false</literal>,
+       invalid string is passed.  Previously, it returned &false;,
        and a warning was emitted.
       </entry>
      </row>
diff --git a/reference/filter/constants.xml b/reference/filter/constants.xml
@@ -285,14 +285,14 @@
     <simpara>
      Returns &true; for <literal>"1"</literal>,
      <literal>1</literal> including binary, octal and hexadecimal notations, <literal>1.0</literal> including scientific notation,
-     <literal>"true"</literal>, <literal>true</literal>,
+     <literal>"true"</literal>, &true;,
      <literal>"on"</literal>,
      and <literal>"yes"</literal>.
     </simpara>
     <simpara>
      Returns &false; for <literal>"0"</literal>,
      <literal>0</literal> including binary, octal and hexadecimal notations, <literal>0.0</literal> including scientific notation,
-     <literal>"false"</literal>, <literal>false</literal>,
+     <literal>"false"</literal>, &false;,
      <literal>"off"</literal>,
      <literal>"no"</literal>, and
      <literal>""</literal>.
diff --git a/reference/info/functions/ini-get.xml b/reference/info/functions/ini-get.xml
@@ -35,11 +35,11 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
+  <simpara>
    Returns the value of the configuration option as a string on success, or an
-   empty string for <literal>null</literal> values. Returns &false; if the
+   empty string for &null; values. Returns &false; if the
    configuration option doesn't exist.
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="examples">
diff --git a/reference/intl/ini.xml b/reference/intl/ini.xml
@@ -51,13 +51,13 @@
       <type>string</type>
      </term>
      <listitem>
-      <para>
+      <simpara>
        The locale that will be used in intl functions when none is specified
        (either by omitting the corresponding argument or by passing
-       <literal>NULL</literal>). These are ICU locales, not system locales.
+       &null;). These are ICU locales, not system locales.
        The built-in ICU locales and their data can be explored at
        <link xlink:href="&url.icu.locales;"/>.
-      </para>
+      </simpara>
       <para>
        The default value is empty, which forces the usage of ICU's default
        locale. Once set, the ini setting cannot be reset to this default value.
diff --git a/reference/mbstring/functions/mb-strcut.xml b/reference/mbstring/functions/mb-strcut.xml
@@ -62,10 +62,10 @@
     <varlistentry>
      <term><parameter>length</parameter></term>
      <listitem>
-      <para>
-       Length in <emphasis>bytes</emphasis>. If omitted or <literal>NULL</literal>
+      <simpara>
+       Length in <emphasis>bytes</emphasis>. If omitted or &null;
        is passed, extract all bytes to the end of the string.
-      </para>
+      </simpara>
       <para>
        If <parameter>length</parameter> is negative, the returned string will
        end at the <parameter>length</parameter>'th byte counting back from the
diff --git a/reference/mbstring/functions/mb-substr.xml b/reference/mbstring/functions/mb-substr.xml
@@ -59,11 +59,11 @@
     <varlistentry>
      <term><parameter>length</parameter></term>
      <listitem>
-      <para>
+      <simpara>
        Maximum number of characters to use from <parameter>string</parameter>. If
-       omitted or <literal>NULL</literal> is passed, extract all characters to
+       omitted or &null; is passed, extract all characters to
        the end of the string.
-      </para>
+      </simpara>
      </listitem>
     </varlistentry>
     <varlistentry>
diff --git a/reference/pdo/constants.fetch-modes.xml b/reference/pdo/constants.fetch-modes.xml
@@ -1120,7 +1120,7 @@ object(TestEntity)#3 (4) {
   </simpara>
   <caution>
    <simpara>
-    <classname>PDORow</classname> will return <literal>NULL</literal> without
+    <classname>PDORow</classname> will return &null; without
     any error or warning when accessing properties or keys that are not defined.
     This can make errors such as typos or queries not returning expected data
     harder to spot and debug.
diff --git a/reference/pdo/pdo/getattribute.xml b/reference/pdo/pdo/getattribute.xml
@@ -65,10 +65,10 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
+  <simpara>
    A successful call returns the value of the requested PDO attribute.
-   An unsuccessful call returns <literal>null</literal>.
-  </para>
+   An unsuccessful call returns &null;.
+  </simpara>
  </refsect1>
 
  <refsect1 role="errors">
diff --git a/reference/reflection/reflectionenum/getbackingtype.xml b/reference/reflection/reflectionenum/getbackingtype.xml
@@ -11,11 +11,11 @@
    <modifier>public</modifier> <type class="union"><type>ReflectionNamedType</type><type>null</type></type><methodname>ReflectionEnum::getBackingType</methodname>
    <void/>
   </methodsynopsis>
-  <para>
+  <simpara>
    If the enumeration is a Backed Enum, this method will return an instance
    of <classname>ReflectionType</classname> for the backing type of the Enum.
-   If it is not a Backed Enum, it will return <literal>null</literal>.
-  </para>
+   If it is not a Backed Enum, it will return &null;.
+  </simpara>
 
  </refsect1>
 
@@ -26,10 +26,10 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   An instance of <classname>ReflectionNamedType</classname>, or <literal>null</literal>
+  <simpara>
+   An instance of <classname>ReflectionNamedType</classname>, or &null;
    if the Enum has no backing type.
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="changelog">
diff --git a/reference/swoole/swoole/coroutine/lock/lock.xml b/reference/swoole/swoole/coroutine/lock/lock.xml
@@ -28,10 +28,10 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Returns <literal>true</literal> if the lock was acquired successfully,
-   <literal>false</literal> otherwise.
-  </para>
+  <simpara>
+   Returns &true; if the lock was acquired successfully,
+   &false; otherwise.
+  </simpara>
  </refsect1>
 </refentry>
 
diff --git a/reference/swoole/swoole/coroutine/lock/trylock.xml b/reference/swoole/swoole/coroutine/lock/trylock.xml
@@ -28,10 +28,10 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Returns <literal>true</literal> if the lock was acquired successfully,
-   <literal>false</literal> if the lock is not available.
-  </para>
+  <simpara>
+   Returns &true; if the lock was acquired successfully,
+   &false; if the lock is not available.
+  </simpara>
  </refsect1>
 </refentry>
 
diff --git a/reference/swoole/swoole/coroutine/lock/unlock.xml b/reference/swoole/swoole/coroutine/lock/unlock.xml
@@ -39,10 +39,10 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Returns <literal>true</literal> if the lock was released successfully,
-   <literal>false</literal> otherwise.
-  </para>
+  <simpara>
+   Returns &true; if the lock was released successfully,
+   &false; otherwise.
+  </simpara>
  </refsect1>
 </refentry>
 
diff --git a/reference/win32service/rightinfo/get-full-username.xml b/reference/win32service/rightinfo/get-full-username.xml
@@ -25,9 +25,9 @@
 
  <refsect1 role="returnvalues"><!-- {{{ -->
   &reftitle.returnvalues;
-  <para>
-   Return the domain and username or username if domain is <literal>null</literal> or &null; if no username found.
-  </para>
+  <simpara>
+   Returns the domain and username. If the domain is &null;, returns only the username; returns &null; if no username is found.
+  </simpara>
  </refsect1><!-- }}} -->
 
  <refsect1 role="seealso">
