php-doc-ru/language/constants.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 9418ae19ae6ab1d3f1536db986830362b207b1d6 Maintainer: sergey Status: ready -->
<!-- Reviewed: no -->
<chapter xml:id="language.constants" xmlns="http://docbook.org/ns/docbook">
 <title>Константы</title>

 <simpara>
  Константа — идентификатор, или имя, для простого значения. Как подсказывает название,
  это значение нельзя изменять во время работы скрипта
  (кроме <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">
<![CDATA[
<?php

// Правильные имена констант
define("FOO",     "что-то");
define("FOO2",    "что-то ещё");
define("FOO_BAR", "что-то большее");

// Неправильные имена констант
define("2FOO",    "что-то");

// Это верное объявление, но лучше его не использовать:
// PHP однажды может зарегистрировать волшебную константу,
// которая нарушит работу скрипта
define("__FOO__", "что-то");

?>
]]>
   </programlisting>
  </example>
 </para>
 <note>
  <simpara>
   Понятие «буквы» здесь — символы a-z, A-Z,
   и другие символы с ASCII-кодами от 128 до 255 (0x80-0xff).
  </simpara>
 </note>

 <simpara>
  Как и &link.superglobals;, константы доступны из любой области видимости.
  Константы разрешается использовать из любого места скрипта независимо от области видимости.
  Подробную информацию об областях видимости можно найти
  <link linkend="language.variables.scope">здесь</link>.
 </simpara>

 <note>
   <simpara>
    Начиная с PHP 7.1.0 константам класса доступны объявления видимости — защищённая
    или закрытая, которые делают константу доступной только в иерархической области видимости
    класса, в котором константа определена.
   </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>
   Значение константы получают по имени константы.
   <emphasis>Не нужно</emphasis> указывать перед именем константы символ
   <literal>$</literal>, как перед переменными.
   Значение константы также получают функцией <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 сравнивалось с "CONSTANT".
   Этот резервный вариант объявили устаревшим в PHP 7.2.0, при этом будет
   сгенерирована ошибка уровня <constant>E_WARNING</constant>.
   До PHP 7.2.0 вместо этого выдавалась ошибка уровня <link linkend="ref.errorfunc">E_NOTICE</link>.
   Смотрите также главу руководства, которая разъясняет, почему
   <link linkend="language.types.array.foo-bar">$foo[bar]</link> —
   это неправильно (если только <literal>bar</literal> не константа).
   Это не относится к <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", "Здравствуй, мир.");
echo CONSTANT; // Выводит "Здравствуй, мир."
echo Constant; // Выбросит ошибку: Неопределённая константа Constant
               // До PHP 8.0.0 выводит "Constant" и выдаёт предупреждение.

?>
]]>
    </programlisting>
   </example>
  </para>

  <para>
   <example>
    <title>Определение констант через ключевое слово <literal>const</literal></title>
    <programlisting role="php">
<![CDATA[
<?php

// Простое скалярное значение
const CONSTANT = 'Здравствуй, мир.';

echo CONSTANT;

// Скалярное выражение
const ANOTHER_CONST = CONSTANT . ' Прощай, мир.';
echo ANOTHER_CONST;

const ANIMALS = array('dog', 'cat', 'bird');
echo ANIMALS[1]; // выводит "cat"

// Массивы в константе
define('ANIMALS', array(
    'dog',
    'cat',
    'bird'
));
echo ANIMALS[1]; // выводит "cat"

?>
]]>
    </programlisting>
   </example>
  </para>

  <note>
   <para>
    В отличие от определения констант функцией <function>define</function>,
    константы, которые объявили через ключевое слово <literal>const</literal>,
    требуется объявлять в самой верхней области видимости, потому что константы
    определяются при компилировании скрипта. Поэтому константы нельзя объявлять
    внутри функций, циклов, инструкций <literal>if</literal>, или блоков <literal>try</literal>
    и <literal>catch</literal>.
   </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> для каждого скрипта, который он запускает.
   При этом многие константы из этого списка создают модули. Поэтому константы
   будут представлены только тогда, когда доступны модули, которые либо динамически загрузили,
   либо включили в сборку PHP при компиляции.
  </simpara>
 </sect1>

 <sect1 xml:id="language.constants.magic">
  <title>Магические константы</title>
  <para>
   PHP включает несколько магических констант, значение которых изменяется в зависимости от контекста.
   Например, значение константы <constant>__LINE__</constant> зависит от строки скрипта,
   на которой указали константу. PHP разрешает «магические» константы
   во время компиляции, в отличие от стандартных констант, которые PHP разрешает
   во время выполнения. Специальные константы нечувствительны
   к регистру, а их список приводит следующий параграф:
  </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>
        Полный путь и имя текущего файла с разрешёнными символическими ссылками.
        PHP возвращает имя подключённого файла, если константу указали внутри него.
       </entry>
      </row>
      <row xml:id="constant.dir">
       <entry><constant>__DIR__</constant></entry>
       <entry>
        Каталог файла. PHP возвращает каталог подключённого файла, если константу
        указали внутри подключаемого файла.
        Значение константы эквивалентно вызову
        <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>.
        Внутри методов трейтов значение константы __CLASS__ равно названию класса, в котором вызывают метод трейта.
       </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
-->