php-doc-en/language/constants.xml

<?xml encoding="iso-8859-1"?>
<!-- $Revision: 1.19 $ -->
 <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
   (the magic constants <constant>__FILE__</constant> and 
   <constant>__LINE__</constant> are the only exception). A constant
   is case-sensitive by default. By convention constants 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>
   The scope of a constant is global.
  </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>double</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="features.error-handling">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>
    This are the differences with 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.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    
   <para>
    <example>
     <title>Defining Constants</title>
     <programlisting>
&lt;?php
define("CONSTANT", "Hello world.");
echo CONSTANT; // outputs "Hello world."
echo Constant; // outputs "Constant" and issues a notice.
?&gt;
     </programlisting>
    </example>

   </para>
   
  </sect1>
  
  <sect1 id="language.constants.predefined">
   <title>Predefined constants</title>
  <para>
   The predefined constants (always available) are:

   <variablelist>

    <varlistentry>
     <term>__FILE__  (case-insensitive)</term>
     <listitem>
      <simpara>
       The name of the script file presently being parsed. If used
       within a file which has been included or required, then the
       name of the included file is given, and not the name of the
       parent file.
      </simpara>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>__LINE__  (case-insensitive)</term>
     <listitem>
      <simpara>
       The number of the line within the current script file which is
       being parsed. If used within a file which has been included or
       required, then the position within the included file is given.
      </simpara>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>PHP_VERSION</term>
     <listitem>
      <simpara>
       The string representation of the version of the PHP parser
       presently in use; for example '4.1.0'.
      </simpara>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>PHP_OS</term>
     <listitem>
      <simpara>
       The name of the operating system on which the PHP parser is
       executing;. Possible values may be : 
       "AIX", "Darwin" (MacOS), "Linux", "SunOS", "WIN32", "WINNT".
       Note: other values may be available too.
      </simpara>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>&true;  (case-insensitive)</term>
     <listitem>
      <simpara>
       A &true; value (see the <type>boolean</type> type).
      </simpara>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>&false;  (case-insensitive)</term>
     <listitem>
      <simpara>
       A &false; value (see the <type>boolean</type> type).
      </simpara>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>&null;  (case-insensitive)</term>
     <listitem>
      <simpara>
       A &null; value (see the <type>null</type> type).
      </simpara>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>E_ERROR</term>
     <listitem>
      <simpara>
       Denotes an error other than a parsing error from which
       recovery is not possible. 
      </simpara>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>E_WARNING</term>
     <listitem>
      <simpara>
       Denotes a condition where PHP knows something is wrong, but
       will continue anyway; these can be caught by the script
       itself. An example would be an invalid regexp in
       <function>ereg</function>.
      </simpara>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>E_PARSE</term>
     <listitem>
      <simpara>
       The parser choked on invalid syntax in the script
       file. Recovery is not possible.
      </simpara>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>E_NOTICE</term>
     <listitem>
      <simpara>
       Something happened which may or may not be an error. Execution
       continues. Examples include using an unquoted string as an array
       index, or accessing a variable which has not been set.
      </simpara>
     </listitem>
    </varlistentry>
    
    <varlistentry>
     <term>E_ALL</term>
     <listitem>
      <simpara>
       All of the E_* constants rolled into one. If used with
       <function>error_reporting</function>, will cause any and all
       problems noticed by PHP to be reported.
      </simpara>
     </listitem>
    </varlistentry>

   </variablelist>
  </para>

   <para>
    The <literal>E_*</literal> constants are typically used with the
    <function>error_reporting</function> function for setting the
    error reporting level. See all these constants at
    <link linkend="features.error-handling">Error handling</link>.

    <example>
     <title>Using __FILE__ and __LINE__</title>
     <programlisting>
&lt;?php
function report_error($file, $line, $message)
{
    echo "An error occured in $file on line $line: $message.";
}

report_error(__FILE__, __LINE__, "Something went wrong!");
?&gt;
     </programlisting>
    </example>
   </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
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
-->