<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
 <chapter xml:id="language.constants" xmlns="http://docbook.org/ns/docbook">
  <title>Constants</title>

  <simpara>
   A constant is an identifier (name) for a simple value. As the name
   suggests, that value cannot change during the execution of the
   script (except for <link linkend="language.constants.magic">
   magic constants</link>, which aren't actually constants).
   Constants are case-sensitive. By convention, constant
   identifiers are always uppercase.
  </simpara>

  <note>
   <para>
    Prior to PHP 8.0.0, constants defined using the <function>define</function>
    function may be case-insensitive.
   </para>
  </note>

  <para>
   The name of a constant follows the same rules as any label in PHP. A 
   valid constant name starts with a letter or underscore, followed
   by any number of letters, numbers, or underscores. As a regular
   expression, it would be expressed thusly:
   <code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>
  </para>
  <para>
   It is possible to <function>define</function> constants with reserved or even
   invalid names, whose value can only be retrieved with the
   <function>constant</function> function. However, doing so is not recommended.
  </para>
  &tip.userlandnaming;
  <para>
<!-- TODO Move into syntax section? -->
   <example>
    <title>Valid and invalid constant names</title>
    <programlisting role="php">
<![CDATA[
<?php

// Valid constant names
define("FOO",     "something");
define("FOO2",    "something else");
define("FOO_BAR", "something more");

// Invalid constant names
define("2FOO",    "something");

// This is valid, but should be avoided:
// PHP may one day provide a magical constant
// that will break your script
define("__FOO__", "something"); 

?>
]]>
    </programlisting>
   </example>
  </para>
  <note>
   <simpara>
    For our purposes here, a letter is a-z, A-Z, and the ASCII
    characters from 128 through 255 (0x80-0xff).
   </simpara>
  </note>

  <simpara>
   Like &link.superglobals;, the scope of a constant is global.
   Constants can be accessed from anywhere in a script without regard to scope.
   For more information on scope, read the manual section on
   <link linkend="language.variables.scope">variable scope</link>.
  </simpara>

  <note>
   <simpara>
    As of PHP 7.1.0, class constant may declare a visibility of protected
    or private, making them only available in the hierarchical scope of the
    class in which it is defined.
   </simpara>
  </note>

  <sect1 xml:id="language.constants.syntax">
   <title>Syntax</title>
   <simpara>
    Constants can be defined using the <literal>const</literal> keyword,
    or by using the <function>define</function>-function.
    While <function>define</function> allows a constant to be
    defined to an arbitrary expression, the <literal>const</literal> keyword has
    restrictions as outlined in the next paragraph.
    Once a constant is defined, it can never be
    changed or undefined.
   </simpara>
   <simpara>
    When using the <literal>const</literal> keyword,
    only scalar (<type>bool</type>, <type>int</type>,
    <type>float</type> and <type>string</type>) expressions and constant
    <type>array</type>s containing only scalar expressions are accepted.
    It is possible to define constants as a <type>resource</type>,
    but it should be avoided, as it can cause unexpected results.
   </simpara>
   <simpara>
    The value of a constant is accessed simply by specifying its name.
    Unlike variables, a constant is <emphasis>not</emphasis> prepended
    with a <literal>$</literal>.
    It is also possible to use the <function>constant</function> function to
    read a constant's value if the constant's name is obtained dynamically. 
    Use <function>get_defined_constants</function> to get a list of 
    all defined constants.
   </simpara>

   <note>
    <simpara>
     Constants and (global) variables are in a different namespace. 
     This implies that for example &true; and 
     <varname>$TRUE</varname> are generally different.
    </simpara>
   </note>

   <simpara>
    If an undefined constant is used an <classname>Error</classname> is thrown.
    Prior to PHP 8.0.0, undefined constants would be interpreted as a bare
    word <type>string</type>, i.e. (CONSTANT vs "CONSTANT"). 
    This fallback is deprecated as of PHP 7.2.0, and an error of level
    <constant>E_WARNING</constant> is issued when it happens.
    Prior to PHP 7.2.0, an error of level
    <link linkend="ref.errorfunc">E_NOTICE</link> has been issued instead.
    See also the manual entry on why 
    <link linkend="language.types.array.foo-bar">$foo[bar]</link> is
    wrong (unless <literal>bar</literal> is a constant).
    This does not apply to <link
    linkend="language.namespaces.rules">(fully) qualified constants</link>,
    which will always raise a <classname>Error</classname> if undefined.
   </simpara>

   <note>
    <simpara>
     To check if a constant is set, use the <function>defined</function> function.
    </simpara>
   </note>

   <para>
    These are the differences between constants and variables:
    <itemizedlist>
     <listitem>
      <simpara>
       Constants do not have a dollar sign (<literal>$</literal>)
       before them;
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Constants may be defined and accessed anywhere without regard
       to variable scoping rules;
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Constants may not be redefined or undefined once they have been
       set; and
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Constants may only evaluate to scalar values or arrays.
      </simpara>
     </listitem>
    </itemizedlist>
   </para>

   <para>
    <example>
     <title>Defining Constants</title>
     <programlisting role="php">
<![CDATA[
<?php
define("CONSTANT", "Hello world.");
echo CONSTANT; // outputs "Hello world."
echo Constant; // Emits an Error: Undefined constant "Constant"
               // Prior to PHP 8.0.0, outputs "Constant" and issues a warning.
?>
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title>Defining Constants using the <literal>const</literal> keyword</title>
     <programlisting role="php">
<![CDATA[
<?php
// Simple scalar value
const CONSTANT = 'Hello World';

echo CONSTANT;

// Scalar expression
const ANOTHER_CONST = CONSTANT.'; Goodbye World';
echo ANOTHER_CONST;

const ANIMALS = array('dog', 'cat', 'bird');
echo ANIMALS[1]; // outputs "cat"

// Constant arrays
define('ANIMALS', array(
    'dog',
    'cat',
    'bird'
));
echo ANIMALS[1]; // outputs "cat"
?>
]]>
     </programlisting>
    </example>
   </para>

   <note>
    <para>
     As opposed to defining constants using <function>define</function>,
     constants defined using the <literal>const</literal> keyword must be
     declared at the top-level scope because they are defined at compile-time.
     This means that they cannot be declared inside functions, loops,
     <literal>if</literal> statements or
     <literal>try</literal>/<literal>catch</literal> blocks.
    </para>
   </note>

   <sect2 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><link linkend="language.oop5.constants">Class Constants</link></member>
     </simplelist>
    </para>
   </sect2>
  </sect1>
  
  <sect1 xml:id="language.constants.predefined">
   <title>Predefined constants</title>

   <simpara>
    PHP provides a large number of <link
    linkend="reserved.constants">predefined constants</link> to any script
    which it runs. Many of these constants, however, are created by
    various extensions, and will only be present when those extensions
    are available, either via dynamic loading or because they have
    been compiled in.
   </simpara>
  </sect1>

  <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>

   <sect2 role="seealso">
    &reftitle.seealso;
    <para>
     <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>
     </simplelist>
    </para>
   </sect2>

  </sect1>
 </chapter>
 
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->