php-doc-en/language/constants.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.29 $ -->
 <chapter id="language.constants">
  <title>Constants</title>

  <simpara>
   A constant is a identifier (name) for a simple value. As the name
   suggests, that value cannot change during the execution of the
   script (except the <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 thus:
   <literal>[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*</literal>

   <!-- TODO: Example of valid & invalid constant names -->
  </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 are 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. A 
    <link linkend="ref.errorfunc">notice</link> will be issued
    when this happens. Use the <function>defined</function>-function if 
    you want to know if a constant is set.
   </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>Predefined constants</title>

   <simpara>
    PHP provides a large number of predefined constants 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 four magical constants that change depending on
    where they're 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>
      </tbody>
     </tgroup>
    </table>
   </para>

   <simpara>
    A list of predefined constants is available in the section <link
    linkend="reserved.constants">Reserved predefined constants</link>.
   </simpara>


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