[doc-en] master: Rewrite the magic constants section (#5882)

Author: Kamil Tekiela (kamil-tekiela) Committer: GitHub (web-flow) Pusher: kamil-tekiela Date: 2026-09-26T18:05:15+01:00 Commit: https://github.com/php/doc-en/commit/5dc21d42fd5c1a8d6b0e45869c4fe3c3ac8e9a2c Raw diff: https://github.com/php/doc-en/commit/5dc21d42fd5c1a8d6b0e45869c4fe3c3ac8e9a2c.diff Rewrite the magic constants section (#5882) Changed paths: M language/constants.xml Diff: diff --git a/language/constants.xml b/language/constants.xml index bfd8e3d87e83..42448e5d1318 100644 --- a/language/constants.xml +++ b/language/constants.xml @@ -280,100 +280,151 @@ echo ANIMALS_DEF[1] . "\n"; // outputs "cat" <sect1 xml:id="language.constants.magic"> <title>Magic constants</title> - <para> - There are a few magical constants that change depending on - where they are used. For example, the value of - <constant>__LINE__</constant> depends on the line that it's - used on in a script. All these "magical" constants are resolved - at compile time, unlike regular constants, which are resolved at runtime. - These special constants are case-insensitive and are as follows: - </para> - <para> - <table> - <title>PHP's magic constants</title> - <tgroup cols="2"> - <thead> - <row> - <entry>&Name;</entry> - <entry>&Description;</entry> - </row> - </thead> - <tbody> - <row xml:id="constant.line"> - <entry><constant>__LINE__</constant></entry> - <entry> - The current line number of the file. - </entry> - </row> - <row xml:id="constant.file"> - <entry><constant>__FILE__</constant></entry> - <entry> - The full path and filename of the file with symlinks resolved. If used inside an include, - the name of the included file is returned. - </entry> - </row> - <row xml:id="constant.dir"> - <entry><constant>__DIR__</constant></entry> - <entry> - The directory of the file. If used inside an include, - the directory of the included file is returned. This is equivalent - to <literal>dirname(__FILE__)</literal>. This directory name - does not have a trailing slash unless it is the root directory. - </entry> - </row> - <row xml:id="constant.function"> - <entry><constant>__FUNCTION__</constant></entry> - <entry> - The function name, or <literal>{closure}</literal> for anonymous functions. - </entry> - </row> - <row xml:id="constant.class"> - <entry><constant>__CLASS__</constant></entry> - <entry> - The class name. The class name includes the namespace - it was declared in (e.g. <literal>Foo\Bar</literal>). - When used inside a trait method, - <constant>__CLASS__</constant> is the name of the class the trait - is used in. - </entry> - </row> - <row xml:id="constant.trait"> - <entry><constant>__TRAIT__</constant></entry> - <entry> - The trait name. The trait name includes the namespace - it was declared in (e.g. <literal>Foo\Bar</literal>). - </entry> - </row> - <row xml:id="constant.method"> - <entry><constant>__METHOD__</constant></entry> - <entry> - The class method name. - </entry> - </row> - <row xml:id="constant.property"> - <entry><constant>__PROPERTY__</constant></entry> - <entry> - Only valid inside a - <link linkend="language.oop5.property-hooks">property hook</link>. - It is equal to the name of the property. - </entry> - </row> - <row xml:id="constant.namespace"> - <entry><constant>__NAMESPACE__</constant></entry> - <entry> - The name of the current namespace. - </entry> - </row> - <row xml:id="constant.coloncolonclass"> - <entry><constant><replaceable>ClassName</replaceable>::class</constant></entry> - <entry> - The fully qualified class name. - </entry> - </row> - </tbody> - </tgroup> - </table> - </para> + <simpara> + Magic constants are keywords that are replaced with information about + their own location in the source code: their file and line, and the + function, class, trait, namespace, or property hook enclosing them. + Despite their name, they are not actual constants: + <function>defined</function> and <function>constant</function> do not + recognize them, and a constant of the same name created with + <function>define</function> does not affect them. They are case-insensitive. + When used outside of the relevant context (e.g. <constant>__CLASS__</constant> + outside of a class), they are replaced with an empty string. + </simpara> + <table> + <title>PHP's magic constants</title> + <tgroup cols="2"> + <thead> + <row> + <entry>&Name;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row xml:id="constant.line"> + <entry><constant>__LINE__</constant></entry> + <entry> + The line number on which it is written. + </entry> + </row> + <row xml:id="constant.file"> + <entry><constant>__FILE__</constant></entry> + <entry> + The full path and filename of the file in which it is written, + with symlinks resolved. + </entry> + </row> + <row xml:id="constant.dir"> + <entry><constant>__DIR__</constant></entry> + <entry> + The directory of the file, equivalent to + <literal>dirname(__FILE__)</literal>. It has no trailing slash + unless it is the root directory. + </entry> + </row> + <row xml:id="constant.function"> + <entry><constant>__FUNCTION__</constant></entry> + <entry> + The name of the function in which it is written, including its namespace + (e.g. <literal>Foo\bar</literal>). + Inside a method, only the method name. + For anonymous functions, a name generated by the engine that includes + where the closure was defined (as of PHP 8.4.0; previously + <literal>{closure}</literal>). + </entry> + </row> + <row xml:id="constant.class"> + <entry><constant>__CLASS__</constant></entry> + <entry> + The name of the class in which it is written, including its namespace + (e.g. <literal>Foo\Bar</literal>). + Inside a trait, the name of the class using the trait. + For <link linkend="language.oop5.anonymous">anonymous classes</link>, + a name generated by the engine. + To get the name of the class a method was called on, use + <link linkend="language.oop5.late-static-bindings"><literal>static::class</literal></link>. + </entry> + </row> + <row xml:id="constant.trait"> + <entry><constant>__TRAIT__</constant></entry> + <entry> + The trait name, including its namespace (e.g. <literal>Foo\Bar</literal>). + </entry> + </row> + <row xml:id="constant.method"> + <entry><constant>__METHOD__</constant></entry> + <entry> + The class and method name of the method in which it is written + (e.g. <literal>Foo\Bar::baz</literal>). + Inside a trait, the trait name is used instead of the class name. + Outside of a method, the same as <constant>__FUNCTION__</constant>. + </entry> + </row> + <row xml:id="constant.property"> + <entry><constant>__PROPERTY__</constant></entry> + <entry> + The name of the property, when used inside a + <link linkend="language.oop5.property-hooks">property hook</link>. + Available as of PHP 8.4.0. + </entry> + </row> + <row xml:id="constant.namespace"> + <entry><constant>__NAMESPACE__</constant></entry> + <entry> + The name of the current namespace. + </entry> + </row> + </tbody> + </tgroup> + </table> + + <example> + <title>Using magic constants</title> + <programlisting role="php"> +<![CDATA[ +<?php +namespace App; + +function helper() +{ + echo __FUNCTION__, "\n"; + echo __METHOD__, "\n"; +} + +trait Greets +{ + public function greet() + { + echo __CLASS__, "\n"; + echo __TRAIT__, "\n"; + echo __METHOD__, "\n"; + echo __FUNCTION__, "\n"; + } +} + +class Greeter +{ + use Greets; +} + +helper(); +(new Greeter)->greet(); +echo __NAMESPACE__, "\n"; +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +App\helper +App\helper +App\Greeter +App\Greets +App\Greets::greet +greet +App +]]> + </screen> + </example> <sect2 role="seealso"> &reftitle.seealso; @@ -381,9 +432,8 @@ echo ANIMALS_DEF[1] . "\n"; // outputs "cat" <simplelist> <member><link linkend="language.oop5.basic.class.class">::class</link></member> <member><function>get_class</function></member> - <member><function>get_object_vars</function></member> - <member><function>file_exists</function></member> - <member><function>function_exists</function></member> + <member><function>get_called_class</function></member> + <member><function>dirname</function></member> </simplelist> </para> </sect2>