[doc-en] master: Add namespace caveats to define(), defined(), and constant() (#5256)

From: Date: Tue, 01 Sep 2026 12:20:52 +0000
Subject: [doc-en] master: Add namespace caveats to define(), defined(), and constant() (#5256)
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-23684@lists.php.net to get a copy of this message
Author: Louis-Arnaud (lacatoire) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-01T14:20:49+02:00 Commit: https://github.com/php/doc-en/commit/5dc2deaf9f59287a5a5e327b7de538a9ff3fddf2 Raw diff: https://github.com/php/doc-en/commit/5dc2deaf9f59287a5a5e327b7de538a9ff3fddf2.diff Add namespace caveats to define(), defined(), and constant() (#5256) These functions take the constant name as an ordinary string and never resolve it against the current namespace, so the namespace has to be part of the name. An unqualified name is looked up in the global namespace, which can silently return a different constant than the same bare identifier would, and define() places the constant in the global namespace without any error. Unlike defined() and constant(), define() does not strip a leading namespace separator, so define('\My\Namespace\MYCONST', 1) succeeds but creates a constant that can never be retrieved. Also note the escaping needed in double-quoted strings and the case rules. Fixes #4628 Changed paths: M reference/misc/functions/constant.xml M reference/misc/functions/define.xml M reference/misc/functions/defined.xml Diff: diff --git a/reference/misc/functions/constant.xml b/reference/misc/functions/constant.xml index 5a0ac642fb0f..d7d0c059ade7 100644 --- a/reference/misc/functions/constant.xml +++ b/reference/misc/functions/constant.xml @@ -38,6 +38,27 @@ <para> The constant name. </para> + <note> + <simpara> + <function>constant</function> takes the name as an ordinary + <type>string</type> and does not resolve it against the current + <link linkend="language.namespaces.dynamic">namespace</link>: the name + is looked up in the global namespace, so an unqualified name may + silently return a different constant from the one the same bare + identifier would refer to. + To retrieve the value of a constant declared in a namespace, the + namespace must be part of the name, as in + <literal>constant('My\Namespace\MYCONST')</literal> or + <literal>constant(__NAMESPACE__ . '\MYCONST')</literal>. + Because the name is a plain string, aliases introduced by + <literal>use</literal> statements and the + <literal>namespace\</literal> prefix are not applied to it. + In a double-quoted string the namespace separators must be escaped, + as in <literal>"My\\Namespace\\MYCONST"</literal>. + The namespace part of the name is case-insensitive, the constant name + is not. + </simpara> + </note> </listitem> </varlistentry> </variablelist> diff --git a/reference/misc/functions/define.xml b/reference/misc/functions/define.xml index 6fd5cd0a422a..b4c4e75d6bfd 100644 --- a/reference/misc/functions/define.xml +++ b/reference/misc/functions/define.xml @@ -35,6 +35,27 @@ even invalid names, whose value can (only) be retrieved with <function>constant</function>. However, doing so is not recommended. </para> + <simpara> + <function>define</function> takes the name as an ordinary + <type>string</type> and does not resolve it against the current + <link linkend="language.namespaces.dynamic">namespace</link>. + Inside <literal>namespace My\Namespace;</literal>, + <literal>define('MYCONST', 1)</literal> therefore defines + <literal>MYCONST</literal> in the global namespace, silently and + without error. + To place the constant in a namespace, the namespace must be part of + the name, written without a leading namespace separator, as in + <literal>define('My\Namespace\MYCONST', 1)</literal> or + <literal>define(__NAMESPACE__ . '\MYCONST', 1)</literal>. + Unlike <function>defined</function> and <function>constant</function>, + <function>define</function> does not strip a leading separator: + <literal>define('\My\Namespace\MYCONST', 1)</literal> returns &true; + but creates a constant that can never be retrieved. + Because the name is a plain string, aliases introduced by + <literal>use</literal> statements are not applied to it. + In a double-quoted string the namespace separators must be escaped, + as in <literal>"My\\Namespace\\MYCONST"</literal>. + </simpara> </note> </listitem> </varlistentry> diff --git a/reference/misc/functions/defined.xml b/reference/misc/functions/defined.xml index 83b00e06f3a1..668713709883 100644 --- a/reference/misc/functions/defined.xml +++ b/reference/misc/functions/defined.xml @@ -40,6 +40,27 @@ <para> The constant name. </para> + <note> + <simpara> + <function>defined</function> takes the name as an ordinary + <type>string</type> and does not resolve it against the current + <link linkend="language.namespaces.dynamic">namespace</link>: the name + is looked up in the global namespace, so an unqualified name may + silently report on a different constant from the one the same bare + identifier would refer to. + To check whether a constant declared in a namespace is defined, the + namespace must be part of the name, as in + <literal>defined('My\Namespace\MYCONST')</literal> or + <literal>defined(__NAMESPACE__ . '\MYCONST')</literal>. + Because the name is a plain string, aliases introduced by + <literal>use</literal> statements and the + <literal>namespace\</literal> prefix are not applied to it. + In a double-quoted string the namespace separators must be escaped, + as in <literal>"My\\Namespace\\MYCONST"</literal>. + The namespace part of the name is case-insensitive, the constant name + is not. + </simpara> + </note> </listitem> </varlistentry> </variablelist>

« previous php.doc.cvs (#23684) next »