[DOC-CVS] [doc-en] master: Use &true;/&false;/&null; entities for boolean/null constants (#5641)
[email protected] (Louis-Arnaud via GitHub) Thu, 9 Jul 2026 17:41:59 +0000
| Newsgroups | php.doc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: jordikroon
Date: 2026-07-09T19:41:57+02:00
Commit: https://github.com/php/doc-en/commit/911fe79de766ef4475bf22446903667a0f3a24d3
Raw diff: https://github.com/php/doc-en/commit/911fe79de766ef4475bf22446903667a0f3a24d3.diff
Use &true;/&false;/&null; entities for boolean/null constants (#5641)
* Use &true;/&false;/&null; entities for boolean/null constants
Replace <literal>true/false/null</literal> 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.
Changed paths:
M language/control-structures/include.xml
M language/enumerations.xml
M language/oop5/overloading.xml
M language/predefined/weakreference.xml
M language/types/array.xml
M language/types/declarations.xml
M reference/datetime/dateinterval/createfromdatestring.xml
M reference/datetime/datetime/modify.xml
M reference/datetime/datetimeimmutable/modify.xml
M reference/filter/constants.xml
M reference/info/functions/ini-get.xml
M reference/intl/ini.xml
M reference/mbstring/functions/mb-strcut.xml
M reference/mbstring/functions/mb-substr.xml
M reference/pdo/constants.fetch-modes.xml
M reference/pdo/pdo/getattribute.xml
M reference/reflection/reflectionenum/getbackingtype.xml
M reference/swoole/swoole/coroutine/lock/lock.xml
M reference/swoole/swoole/coroutine/lock/trylock.xml
M reference/swoole/swoole/coroutine/lock/unlock.xml
M reference/win32service/rightinfo/get-full-username.xml
Diff:
diff --git a/language/control-structures/include.xml b/language/control-structures/include.xml
index 33a91ebc79dc..d2de8cb4450d 100644
--- 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
index 8a346156ccce..ac543de3ab87 100644
--- 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
index 40fb5cb44a87..dd2ec3cbba04 100644
--- 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
index f8c040eb8156..7cd4ad494b78 100644
--- 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
index 5ecc93e8d368..a45389522570 100644
--- 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
index 7946793f928f..03fc89f0b984 100644
--- 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
index 6e06f46c92e2..886cac0d345b 100644
--- 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
index 73352a56c8c5..f8e95d50ce15 100644
--- 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
index 19786b6b3a2d..961d86be6ed3 100644
--- 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
index 9ae0a4d0c1d5..88bd5bb64281 100644
--- 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
index 5f8163c87946..06080a59e817 100644
--- 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
index 0c337acde25c..f3b1ee19c13e 100644
--- 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
index 9bcee3884b35..c1b5085eb0e6 100644
--- 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
index 47e63dea6a31..7f769da05fdb 100644
--- 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
index 9ea4dbc81c44..c72182149b29 100644
--- 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
index 8e508487b43b..370d61cb4808 100644
--- 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
index e637dc9781fe..9a7ec8a4a719 100644
--- 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
index 41421d671529..8983fb79ccb8 100644
--- 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
index 19a75d354e8a..f9faa0deb5ec 100644
--- 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
index d9d69d377aff..ce1d7530a520 100644
--- 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
index d46664f59151..e5272637245b 100644
--- 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">