constants.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 6e885e52412ad979aa5fbb620bb84e886fc0ebe8 Maintainer: hirokawa Status: ready -->
<!-- CREDITS: takagi,mumumu -->

 <chapter xml:id="language.constants" xmlns="http://docbook.org/ns/docbook" annotations="interactive">
  <title>定数</title>

  <simpara>
   定数は、値のためのID(名前)です。この名前が示すように、定数の値は
   スクリプト実行中に変更できません (<link 
   linkend="language.constants.magic">マジック定数</link>
   は例外です。これは実際は定数ではありません)。
   定数は大文字小文字を区別します。慣習的に、
   定数は常に大文字で表記されます。
  </simpara>

  <note>
   <para>
    PHP 8.0.0 より前のバージョンでは、
    <function>define</function> 関数を使って定義された定数は、
    大文字小文字を区別しない場合がありました。
   </para>
  </note>

  <para>
   定数の名前は、PHP のラベルと同じ規則に従います。有効な定数の名前は、
   文字またはアンダースコアで始まり、任意の数の文字、数字、
   アンダースコアが後に続きます。正規表現で示すと次のようになります。
   <code>^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$</code>
  </para>
  <para>
   <function>define</function> 関数を使うと、
   予約語や有効でない名前の定数を定義することが可能です。
   この場合の定数の値は <function>constant</function> 関数によってのみ取得できますが、
   このような使い方は推奨できません。
  </para>
  &tip.userlandnaming;
  <para>
<!-- TODO Move into syntax section? -->
   <example>
    <title>有効/無効な定数名の例</title>
    <programlisting role="php" annotations="non-interactive">
<![CDATA[
<?php

// 有効な定数名
define("FOO",     "something");
define("FOO2",    "something else");
define("FOO_BAR", "something more");

// 無効な定数名
define("2FOO",    "something");

// 有効だが、避けるべき。
// 将来 PHP に定数の予約語が追加された場合に
// スクリプトが動作しなくなる可能性がある
define("__FOO__", "something"); 
]]>
    </programlisting>
   </example>
  </para>
  <note>
   <simpara>
    本節の目的においては、文字は a-z, A-Z, および128から255まで
    (0x80-0xff)のASCII文字を指します。
   </simpara>
  </note>

  <simpara>
   &link.superglobals;と同様に定数のスコープはグローバルです。
   つまり、スコープによらずスクリプトの中ではどこでも定数に
   アクセスできます。スコープの詳細についてはマニュアルの
   <link linkend="language.variables.scope">変数のスコープ</link>
   をご覧ください。
  </simpara>

  <note>
   <simpara>
    PHP 7.1.0 以降では、クラス定数は protected または private として宣言でき、
    それが定義されたクラス階層のスコープでのみ利用可能にすることができます。
   </simpara>
  </note>

  <sect1 xml:id="language.constants.syntax">
   <title>構文</title>
   <simpara>
    <literal>const</literal> キーワードか、
    <function>define</function> 関数を使うことで、定数を宣言することが出来ます。
    <function>define</function> を使えば任意の式を使って定数を定義できますが、
    <literal>const</literal> キーワードを使う場合には、
    次の段落で説明する制約があります。
    定数が一度定義されると、
    変更または未定義とすることはできません。
   </simpara>
   <simpara>
    <literal>const</literal> キーワードで定数に指定できるのは、スカラー式
    (<type>bool</type>, <type>int</type>,
    <type>float</type>, <type>string</type>) と、
    スカラー式だけを含んだ <type>array</type> の定数です。
    <type>resource</type> の定数を指定することもできますが、
    予期せぬ結果を引き起こすことがあるので避けるべきです。
   </simpara>
   <simpara>
    単に定数の名前を指定することにより、その値を得ることが可能です。
    変数とは異なり、その前に <literal>$</literal> は<emphasis>不要</emphasis>です。
    定数の名前を動的に得る必要がある場合、定数の値を読むために関数
    <function>constant</function> を使用することも可能です。
    定義済の定数の一覧を得るには、
    <function>get_defined_constants</function> を使用してください。
   </simpara>

   <note>
    <simpara>
     定数と(グローバル)変数は、異なる名前空間にあります。
     例えば、&true; と <varname>$TRUE</varname> は違うものを意味します。
    </simpara>
   </note>

   <simpara>
    未定義の定数を使用した場合、<classname>Error</classname> がスローされます。
    PHP 8.0.0 より前のバージョンでは、
    未定義の定数は、ちょうど<type>string</type>として
    コールしたかのように(CONSTANT vs "CONSTANT")、
    PHPはその定数自体の名前を使用したと解釈していました。
    このような振る舞いは、PHP 7.2.0
    以降では非推奨となり、<constant>E_WARNING</constant>
    が発生するようになりました。
    (それより前のバージョンでは、
    <link linkend="ref.errorfunc">E_NOTICE</link> が発生していました)
   （<literal>bar</literal>が定数でなければ) なぜ
    <link linkend="language.types.array.foo-bar">$foo[bar]</link>が間違っている
    のかというマニュアルもご覧ください。
    これは <link
    linkend="language.namespaces.rules">完全修飾形式の定数</link>
    には適用されず、この場合は未定義なら <classname>Error</classname> が発生します。
   </simpara>

   <note>
    <simpara>
     定数が設定されているかを確認するには、<function>defined</function> 関数を使って下さい。
    </simpara>
   </note>

   <para>
    変数との違いは次のようになります。
    <itemizedlist>
     <listitem>
      <simpara>
       定数は、前にドル記号(<literal>$</literal>)を要しません。
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       定数は、定義することができ、変数のスコープ規則に関係なく、あら
       ゆる場所からアクセス可能です。
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       定数は一度設定されると再定義または未定義とすることはできません。
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       定数は、スカラー値と配列としてのみ評価可能です。
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
    
   <para>
    <example>
     <title>定数の定義</title>
     <programlisting role="php">
<![CDATA[
<?php
define("CONSTANT", "Hello world.");
echo CONSTANT; // "Hello world."を出力
echo Constant; // エラーが発生: Undefined constant "Constant"
               // PHP 8.0.0 より前のバージョンでは、"Constant" を出力し、警告が発生
]]>
     </programlisting>
    </example>
   </para>

   <para>
    <example>
     <title><literal>const</literal> キーワードによる定数の定義</title>
     <programlisting role="php">
<![CDATA[
<?php
// 単純なスカラー値
const CONSTANT = 'Hello World';

echo CONSTANT . "\n";

// スカラー式
const ANOTHER_CONST = CONSTANT . '; Goodbye World';
echo ANOTHER_CONST . "\n";

const ANIMALS = array('dog', 'cat', 'bird');
echo ANIMALS[1] . "\n"; // 出力は "cat"

// 配列の定数
define('ANIMALS_DEF', array(
    'dog',
    'cat',
    'bird'
));
echo ANIMALS_DEF[1] . "\n"; // 出力は "cat"
]]>
     </programlisting>
    </example>
   </para>

   <note>
    <para>
     <function>define</function> による定数の定義とは反対に、
     <literal>const</literal> キーワードで定義した定数はトップレベルのスコープで宣言しなければなりません。
     これはコンパイル時に定義されるからです。
     つまり、関数、ループ、<literal>if</literal> 文、または
     <literal>try</literal>/<literal>catch</literal> ブロックの内部では宣言できないということです。
    </para>
   </note>

   <note>
    <para>
     PHP 8.0.0 より前のバージョンでは、<function>define</function> 関数を使って定義された定数は、
     大文字小文字を区別しません。
    </para>
   </note>

   <sect2 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><link linkend="language.oop5.constants">クラス定数</link></member>
     </simplelist>
    </para>
   </sect2>

  </sect1>
  
  <sect1 xml:id="language.constants.predefined">
   <title>自動的に定義される定数</title>

   <simpara>
    PHPには実行されるスクリプトで使用可能な多くの
    <link
    linkend="reserved.constants">定義済みの定数</link>があります。
    しかし、これらの定数の多くは、種々の拡張モジュールにより作成され、
    動的なロードやコンパイル時の組込みにより、これらの拡張モジュールが
    使用可能である場合にのみ定義されます。
   </simpara>
  </sect1>

  <sect1 xml:id="language.constants.magic">
   <title>マジック定数</title>
   <para>
    使われる場所によって値が変化する定数（マジック定数）がいくつかあります。
    例えば、<constant>__LINE__</constant>はスクリプト上において
    使われる行によって値が変化します。
    これらの
    "マジック"定数は、実行時に解決される通常の定数とは異なり、コンパイル時に解決されます。
    これらの特別な定数は大文字小文字を区別しません。
    内容は以下のとおりです:
   </para>
   <para>
    <table>
     <title>PHP の "マジック" 定数</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>
         ファイル上の現在の行番号。
        </entry>
       </row>
       <row xml:id="constant.file">
        <entry><constant>__FILE__</constant></entry>
        <entry>
         ファイルのフルパスとファイル名 (シンボリックリンクを解決した後のもの)。
         インクルードされるファイルの中で使用された場合、インクルードされるファイルの名前が返されます。
        </entry>
       </row>
       <row xml:id="constant.dir">
        <entry><constant>__DIR__</constant></entry>
        <entry>
         そのファイルの存在するディレクトリ。include の中で使用すると、
         インクルードされるファイルの存在するディレクトリを返します。
         つまり、これは <literal>dirname(__FILE__)</literal> と同じ意味です。
         ルートディレクトリである場合を除き、ディレクトリ名の末尾にスラッシュはつきません。
        </entry>
       </row>
       <row xml:id="constant.function">
        <entry><constant>__FUNCTION__</constant></entry>
        <entry>
         関数名。無名関数の場合は、<literal>{closure}</literal>
        </entry>
       </row>
       <row xml:id="constant.class">
        <entry><constant>__CLASS__</constant></entry>
        <entry>
         クラス名。
         クラス名には、そのクラスが宣言されている名前空間も含みます
         (例 <literal>Foo\Bar</literal>)。
         トレイトのメソッド内で  <constant>__CLASS__ </constant> を使うと、
         そのトレイトを use しているクラスの名前を返します。
        </entry>
       </row>
       <row xml:id="constant.trait">
        <entry><constant>__TRAIT__</constant></entry>
        <entry>
         トレイト名。
         トレイト名には、宣言された名前空間も含みます
         (例 <literal>Foo\Bar</literal>)。
        </entry>
       </row>
       <row xml:id="constant.method">
        <entry><constant>__METHOD__</constant></entry>
        <entry>
         クラスのメソッド名。
        </entry>
       </row>
       <row xml:id="constant.property">
        <entry><constant>__PROPERTY__</constant></entry>
        <entry>
         プロパティ名。
         <link linkend="language.oop5.property-hooks">プロパティフック</link>
         の内部でのみ使用可能です。
        </entry>
       </row>
       <row xml:id="constant.namespace">
        <entry><constant>__NAMESPACE__</constant></entry>
        <entry>
         現在の名前空間の名前。
        </entry>
       </row>
       <row xml:id="constant.coloncolonclass">
        <entry><constant><replaceable>ClassName</replaceable>::class</constant></entry>
        <entry>
         完全に修飾されたクラス名。
        </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
-->