php-doc-en/language/constants.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.38 $ -->
 <chapter id="language.constants">
  <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.predefined">
   magic constants</link>, which aren't actually constants).
   A constant is case-sensitive by default. By convention, constant 
   identifiers are always uppercase.
  </simpara>
  <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:
   <literal>[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*</literal>
  </para>
  <para>
   <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 127 through 255 (0x7f-0xff).
   </simpara>
  </note>

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

  <sect1 id="language.constants.syntax">
   <title>Syntax</title>
   <simpara>
    You can define a constant by using the 
    <function>define</function>-function. Once a constant is defined,
    it can never be changed or undefined.
   </simpara>
   <simpara>
    Only scalar data (<type>boolean</type>, <type>integer</type>, 
    <type>float</type> and <type>string</type>) can be contained 
    in constants.
   </simpara>
   <simpara>
    You can get the value of a constant by simply specifying its name.
    Unlike with variables, you should <emphasis>not</emphasis> prepend
    a constant with a <literal>$</literal>.
    You can also use the function <function>constant</function> to
    read a constant's value if you wish to obtain the constant's name
    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 you use an undefined constant, PHP assumes that you mean
    the name of the constant itself, just as if you called it as
    a <type>string</type> (CONSTANT vs "CONSTANT").  An error of level
    <link linkend="ref.errorfunc">E_NOTICE</link> will be issued
    when this happens.  See also the manual entry on why 
    <link linkend="language.types.array.foo-bar">$foo[bar]</link> is
    wrong (unless you first <function>define</function>
    <literal>bar</literal> as a constant).  If you simply want to check if a
    constant is set, use the <function>defined</function> function.
   </simpara>
   <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 only be defined using the
       <function>define</function> function, not by simple assignment;
      </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.
       </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; // outputs "Constant" and issues a notice.
?>
]]>
     </programlisting>
    </example>

   </para>
  </sect1>
  
  <sect1 id="language.constants.predefined">
   <title>Magic 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>
   
   <para>
    There are five 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 your script. These special constants are 
    case-insensitive and are as follows:
   </para>
   <para>
    <table>
     <title>A few "magical" PHP constants</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>Name</entry>
        <entry>Description</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry><constant>__LINE__</constant></entry>
        <entry>
         The current line number of the file.
        </entry>
       </row>
       <row>
        <entry><constant>__FILE__</constant></entry>
        <entry>
         The full path and filename of the file.
        </entry>
       </row>
       <row>
        <entry><constant>__FUNCTION__</constant></entry>
        <entry>
         The function name. (This was added in PHP 4.3.0.)
        </entry>
       </row>
       <row>
        <entry><constant>__CLASS__</constant></entry>
        <entry>
         The class name. (This was added in PHP 4.3.0.)
        </entry>
       </row>
       <row>
        <entry><constant>__METHOD__</constant></entry>
        <entry>
         The class method name. (This was added in PHP 5.0.0)
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>

  </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:"../../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
-->