<?xml version="1.0" encoding="utf-8"?>

<chapter xml:id="language.namespaces" xmlns="http://docbook.org/ns/docbook"

version="1.1">

<title>Пространства имён</title>

<sect1 xml:id="language.namespaces.rationale">

<title>Обзор пространств имён</title>

<titleabbrev>Обзор</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<simpara>

Пространства имён, в широком смысле, — способ инкапсуляции

элементов. Такое абстрактное понятие встречается часто. Например, в каждой

операционной системе директории группируют связанные файлы и выступают

в роли пространства имён для находящихся в них файлов. Конкретный пример,

разрешается размещать файл <literal>foo.txt</literal> сразу в обоих каталогах:

<literal>/home/greg</literal> и <literal>/home/other</literal>, но двум копиям

файла <literal>foo.txt</literal> нельзя сосуществовать в одной директории. Кроме сказанного, для доступа

к файлу <literal>foo.txt</literal> извне каталога <literal>/home/greg</literal> надо

через разделитель добавить перед именем файла имя директории, чтобы получить

путь <literal>/home/greg/foo.txt</literal>. Этот же принцип распространяется и на пространства

имён в программировании.

</simpara>

<simpara>

В PHP пространства имён решают две проблемы, с которыми

сталкиваются авторы библиотек и приложений, когда создают переиспользуемые

элементы кода, например классы и функции:

</simpara>

<para>

<orderedlist>

<listitem>

<simpara>

Устраняют конфликт имён между кодом разработчика

и внутренними или внешними классами, функциями, константами PHP.

</simpara>

</listitem>

<listitem>

<simpara>

Создают псевдонимы (или сокращения) для Ну_Очень_Длинных_Имён, чтобы сгладить

первую проблему и улучшить читаемость исходного кода.

</simpara>

</listitem>

</orderedlist>

</para>

<simpara>

Пространства имён в PHP помогают группировать логически связанные

классы, интерфейсы, функции и константы.

</simpara>

<example>

<title>Пример синтаксиса с пространством имён</title>

<programlisting role="php">

</programlisting>

</example>

<note>

<simpara>

Имена пространств имён регистронезависимы.

</simpara>

</note>

<note>

<para>

Название пространства имён «<literal>PHP</literal>» и составные названия,

которые начинаются с этого слова (например, <literal>PHP\Classes</literal>), зарезервированы

для внутренних целей языка, их не нужно писать в пользовательском коде.

</para>

</note>

</sect1>

<sect1 xml:id="language.namespaces.definition">

<title>Определение пространств имён</title>

<titleabbrev>Пространства имён</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Хотя любой корректный PHP-код разрешается размещать внутри пространства имён, только

классы (включая абстрактные классы, трейты и перечисления), интерфейсы, функции и константы зависят от пространства имён.

</para>

<para>

Пространства имён объявляют зарезервированным словом <literal>namespace</literal>,

за которым идёт название пространства имён.

Пространства имён объявляют в начале файла. Другому коду нельзя идти

перед объявлением пространства имён, за исключением зарезервированного слова

<xref linkend="control-structures.declare" />.

<example>

<title>Объявление единого пространства имён</title>

<programlisting role="php">

</programlisting>

</example>

<note>

<simpara>

Абсолютные имена, — которые начинаются с обратной косой черты, —

нельзя включать в объявления пространств имён,

поскольку языковые конструкции с начальным слешем интерпретируются

как выражения относительных пространств имён.

</simpara>

</note>

Перед объявлением пространства имён разрешается указывать только инструкцию

<literal>declare</literal>, чтобы, например, определить кодировку исходного файла. В дополнение,

никакой код, кроме PHP-кода, нельзя размещать перед объявлением пространства имён, включая лишние пробелы:

<example>

<title>Объявление пространства имён</title>

<programlisting role="php">

</programlisting>

</example>

</para>

<para>

В отличие от остальных PHP-конструкций, разрешается определение одного и того же

пространства имён в двух или больше файлах для распределения

содержания пространства имён по файловой системе.

</para>

</sect1>

<sect1 xml:id="language.namespaces.nested">

<title>Определение подпространств имён</title>

<titleabbrev>Подпространства имён</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Аналогично каталогам и файлам, пространства имён PHP разрешают указывать

иерархию названий пространств имён. Поэтому имя пространства разрешается определять

с подуровнями:

<example>

<title>Определение пространства имён с иерархией</title>

<programlisting role="php">

</programlisting>

</example>

Приведённый пример создаёт константу <literal>MyProject\Sub\Level\CONNECT_OK</literal>,

класс <literal>MyProject\Sub\Level\Connection</literal> и функцию

<literal>MyProject\Sub\Level\connect</literal>.

</para>

</sect1>

<sect1 xml:id="language.namespaces.definitionmultiple">

<title>Описание нескольких пространств имён в одном файле</title>

<titleabbrev>Несколько пространств имён в одном файле</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

В одном файле разрешается объявлять больше одного пространства имён.

Многократные пространства имён в одном файле разрешается определять двумя синтаксисами:

</para>

<para>

<example>

<title>Объявление набора пространств имён синтаксисом простой комбинации</title>

<programlisting role="php">

</programlisting>

</example>

</para>

<para>

Этот синтаксис не рекомендуют для комбинирования пространств имён в одном файле.

Вместо него лучше пользоваться альтернативным синтаксисом со скобками.

</para>

<para>

<example>

<title>Объявление набора пространств имён синтаксисом со скобками</title>

<programlisting role="php">

</programlisting>

</example>

</para>

<para>

Практика написания кода настоятельно не рекомендует объединять пространства имён

в одном файле. Главный сценарий того, когда это потребуется, —

объединение нескольких PHP-файлов в один файл.

</para>

<para>

Для объединения кода в глобальном пространстве имён с кодом в других пространствах имён

пользуются только синтаксисом со скобками. Глобальный код должен быть

помещён в конструкцию описания пространства имён без указания имени:

<example>

<title>Описание глобального и обычного пространства имён в одном файле</title>

<programlisting role="php">

</programlisting>

</example>

</para>

<para>

Никакой PHP-код нельзя размещать за пределами скобок пространства имён, кроме

начального выражения declare.

<example>

<title>Описание глобального и обычного пространства имён в одном файле</title>

<programlisting role="php">

</programlisting>

</example>

</para>

</sect1>

<sect1 xml:id="language.namespaces.basics">

<title>Основы пространств имён</title>

<titleabbrev>Основы</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Прежде чем обсуждать работу с пространствами имён, важно понять, как PHP узнаёт,

какие элементы из пространства имён запрашиваются в коде. Можно провести

аналогию между пространствами имён PHP и файловой системой. Есть три способа обратиться

к файлу в файловой системе:

<orderedlist>

<listitem>

<simpara>

Относительное имя файла наподобие <literal>foo.txt</literal> разрешится

в <literal>currentdirectory/foo.txt</literal>, где <literal>currentdirectory</literal> — текущая

директория, в которой мы находимся. Тогда, если текущая директория —

<literal>/home/foo</literal>, то имя преобразуется в <literal>/home/foo/foo.txt</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Относительное имя пути наподобие <literal>subdirectory/foo.txt</literal> разрешится

в <literal>currentdirectory/subdirectory/foo.txt</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Абсолютное имя пути наподобие <literal>/main/foo.txt</literal> останется

таким же: <literal>/main/foo.txt</literal>.

</simpara>

</listitem>

</orderedlist>

Тот же принцип сохранится при разрешении элементов из пространств имён PHP.

Название класса, например, указывают тремя способами:

<orderedlist>

<listitem>

<simpara>

Неполное имя, или название класса без префикса, наподобие

<literal>$a = new foo();</literal>

или <literal>foo::staticmethod();</literal>. В текущем пространстве имён

<literal>currentnamespace</literal> такое название разрешится

в <literal>currentnamespace\foo</literal>. В коде в глобальном

пространстве имён название останется прежним: <literal>foo</literal>.

</simpara>

<simpara>

Предостережение: неполные названия функций и констант разрешаются

в глобальные функции и константы, если их не определили в текущем пространстве имён.

Подробнее об этом рассказывает раздел

«<link linkend="language.namespaces.fallback">Пространства имён: возврат к глобальному пространству для функций и констант</link>».

</simpara>

</listitem>

<listitem>

<simpara>

Полное имя, или название класса с префиксами наподобие

<literal>$a = new subnamespace\foo();</literal>

или <literal>subnamespace\foo::staticmethod();</literal>. В текущем пространстве имён

<literal>currentnamespace</literal> такое название разрешится

в <literal>currentnamespace\subnamespace\foo</literal>. В коде в глобальном

пространстве имён название разрешится в <literal>subnamespace\foo</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Абсолютное имя, или название с префиксом в начале,

который указывает на глобальное пространство имён наподобие

<literal>$a = new \currentnamespace\foo();</literal>

или <literal>\currentnamespace\foo::staticmethod();</literal>. Такое название разрешается

в буквальное, — которое указали в коде: <literal>currentnamespace\foo</literal>.

</simpara>

</listitem>

</orderedlist>

</para>

<para>

Вот пример трёх видов синтаксиса в реальном коде:

<informalexample>

<simpara>file1.php</simpara>

<programlisting role="php">

</programlisting>

<simpara>file2.php</simpara>

<programlisting role="php">

</programlisting>

</informalexample>

</para>

<para>

Обратите внимание, что для доступа к глобальным

классам, функциям или константам разрешается указывать абсолютное имя, например,

<function>\strlen</function>, <classname>\Exception</classname>

или \<constant>INI_ALL</constant>.

<example>

<title>Доступ к глобальным классам, функциям и константам из пространства имён</title>

<programlisting role="php">

</programlisting>

</example>

</para>

</sect1>

<sect1 xml:id="language.namespaces.dynamic">

<title>Пространства имён и динамические особенности языка</title>

<titleabbrev>Пространства имён и динамические особенности языка</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

На реализацию пространств имён в PHP повлияли и динамические свойства языка.

Поэтому, для преобразования кода наподобие следующего примера в код,

который сработает внутри пространства имён:…

<example>

<title>Динамически доступные элементы</title>

<simpara>example1.php:</simpara>

<programlisting role="php">

</programlisting>

</example>

…потребуется указать абсолютное имя — название класса с префиксом пространства имён.

Обратите внимание, поскольку между полным и абсолютным именем

внутри динамического названия класса, функции или константы нет разницы,

начальный обратный слеш не требуется.

<example>

<title>Динамически доступные элементы пространства имён</title>

<programlisting role="php">

</programlisting>

</example>

</para>

<para>

Обязательно прочитайте <link linkend="language.namespaces.faq.quote">примечание об

экранировании имён пространства имён в строках</link>.

</para>

</sect1>

<sect1 xml:id="language.namespaces.nsconstants">

<title>Ключевое слово namespace и магическая константа __NAMESPACE__</title>

<titleabbrev>Ключевое слово namespace и константа __NAMESPACE__</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

PHP поддерживает два способа абстрактного доступа к элементам в текущем пространстве

имён: магическая константа <constant>__NAMESPACE__</constant> и ключевое

слово <literal>namespace</literal>.

</para>

<para>

Значение константы <constant>__NAMESPACE__</constant> — строка, которая содержит

название текущего пространства имён. В глобальном пространстве, вне пространства имён,

константа содержит пустую строку.

<example>

<title>Пример записи константы __NAMESPACE__ в коде с пространством имён</title>

<programlisting role="php">

</programlisting>

</example>

<example>

<title>Пример записи константы __NAMESPACE__ в глобальном пространстве</title>

<programlisting role="php">

</programlisting>

</example>

Константа <constant>__NAMESPACE__</constant> полезна для динамически конструируемых

имён, например:

<example>

<title>Константа __NAMESPACE__ и динамическое конструирование имени</title>

<programlisting role="php">

</programlisting>

</example>

</para>

<para>

Ключевое слово <literal>namespace</literal> разрешается указывать

для явного запроса элемента из текущего пространства имён или из подпространства.

Это эквивалент ключевого слова <literal>self</literal> для классов в пространстве имён.

<example>

<title>Ключевое слово namespace внутри пространства имён</title>

<programlisting role="php">

</programlisting>

</example>

<example>

<title>Ключевое слово namespace в глобальном коде</title>

<programlisting role="php">

</programlisting>

</example>

</para>

</sect1>

<sect1 xml:id="language.namespaces.importing">

<title>Пространства имён: псевдонимирование и импорт</title>

<titleabbrev>Псевдонимирование и импорт</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Способность ссылаться на внешнее абсолютное имя по псевдониму

или импортировать внешние абсолютные имена —

важное свойство пространств имён. Это похоже на способность

файловых систем на основе Unix создавать символические ссылки на файл или директорию.

</para>

<para>

PHP умеет создавать псевдонимы или импортировать константы,

функции, классы, интерфейсы, трейты, перечисления и пространства имён.

</para>

<para>

Псевдоним имени создают через ключевое слово <literal>use</literal>.

Вот пример, который показывает 5 типов импорта:

<example>

<title>Импорт или псевдонимирование через ключевое слово use</title>

<programlisting role="php">

</programlisting>

</example>

Обратите внимание, что именам внутри пространства имён (абсолютным именам пространств имён,

которые содержат разделитель пространств имён, например <literal>Foo\Bar</literal>,

в отличие от глобальных имён, которые его не содержат, например <literal>FooBar</literal>)

начальный обратный слеш (\) не нужен и не рекомендован,

поскольку импортируемые имена должны быть абсолютными и не обрабатываются

относительно текущего пространства имён.

</para>

<para>

PHP дополнительно поддерживает удобное сокращение для задания нескольких операторов

use в одной и той же строке

<example>

<title>Импорт или создание псевдонима через ключевое слово use, комбинирование нескольких выражений</title>

<programlisting role="php">

</programlisting>

</example>

</para>

<para>

Импорт выполняется во время компиляции поэтому не влияет на имена динамических классов,

функций или констант.

<example>

<title>Импорт и динамические имена</title>

<programlisting role="php">

</programlisting>

</example>

</para>

<para>

В дополнение, импорт распространяется только на неполные и полные имена. На абсолютные

имена операция импорта не влияет.

<example>

<title>Импортирование и абсолютные имена</title>

<programlisting role="php">

</programlisting>

</example>

</para>

<sect2 xml:id="language.namespaces.importing.scope">

<title>Обзор правил для импорта</title>

<para>

Ключевое слово <literal>use</literal> должно быть указано в самом начале файла (в

глобальной области) или внутри объявления пространства имён. Это нужно, потому что

импорт выполняется во время компиляции, а не во время исполнения, поэтому его

нельзя ограничить блоком кода. Следующий пример показывает недопустимое указание

ключевого слова <literal>use</literal>:

</para>

<para>

<example>

<title>Недопустимое правило импорта</title>

<programlisting role="php">

</programlisting>

</example>

</para>

<note>

<para>

Правила импорта задают на каждый файл отдельно. Поэтому

присоединяемые файлы <emphasis>НЕ</emphasis> будут наследовать правила импорта

из родительского файла.

</para>

</note>

</sect2>

<sect2 xml:id="language.namespaces.importing.group">

<title>Групповые объявления через ключевое слово <literal>use</literal></title>

<para>

Классы, функции и константы, импортируемые из одного и того же

пространства имён (&namespace;), разрешается группировать в одном

выражении с ключевым словом &use.namespace;.

</para>

<informalexample>

<programlisting role="php">

</programlisting>

</informalexample>

</sect2>

</sect1>

<sect1 xml:id="language.namespaces.global">

<title>Глобальное пространство</title>

<titleabbrev>Глобальное пространство</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Без определения пространства имён определения классов и функций

помещаются в глобальном пространстве — так же, как это было в PHP до введения

пространств имён. Добавление префикса <literal>\</literal> к именам указывает, что

требуется имя из глобального пространства, даже в контексте пространства имён.

<example>

<title>Спецификация глобального пространства</title>

<programlisting role="php">

</programlisting>

</example>

</para>

</sect1>

<sect1 xml:id="language.namespaces.fallback">

<title>Пространства имён: возврат к глобальному пространству для функций и констант</title>

<titleabbrev>Возврат к глобальному пространству</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Когда внутри пространства имён PHP встречает неполное имя класса, функции или

контекст константы, он разрешает эти имена с разными приоритетами. Имена классов

разрешаются в текущее имя пространства имён. Поэтому, чтобы получить доступ

ко внутреннему классу или пользовательскому классу вне пространства имён, необходимо

обращаться к ним по абсолютному имени. Например:

<example>

<title>Доступ к глобальным классам внутри пространства имён</title>

<programlisting role="php">

</programlisting>

</example>

</para>

<para>

PHP будет обращаться к глобальным функциям или константам,

если функция или константа не существует в текущем пространстве имён.

<example>

<title>Возврат к глобальным функциям или константам внутри пространства имён</title>

<programlisting role="php">

</programlisting>

</example>

</para>

</sect1>

<sect1 xml:id="language.namespaces.rules">

<title>Правила разрешения имён</title>

<titleabbrev>Правила разрешения имён</titleabbrev>

<?phpdoc print-version-for="namespaces"?>

<para>

Для целей этих правил разрешения приведём важные определения:

<variablelist>

<title>Определения имени пространства имён</title>

<varlistentry>

<term>Неполное имя</term>

<listitem>

<para>

Идентификатор без разделителя пространств имён, например <literal>Foo</literal>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Полное имя</term>

<listitem>

<para>

Идентификатор с разделителем пространств имён, например <literal>Foo\Bar</literal>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Абсолютное имя</term>

<listitem>

<para>

Идентификатор с разделителем пространств имён, который начинается с разделителя пространств имён,

например <literal>\Foo\Bar</literal>. Пространство имён <literal>\Foo</literal> —

также абсолютное имя.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>Относительное имя</term>

<listitem>

<para>

Идентификатор, который начинается с ключевого слова <literal>namespace</literal>,

например <literal>namespace\Foo\Bar</literal>.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

<para>

Имена разрешаются по следующим правилам:

<orderedlist>

<listitem>

<simpara>

Абсолютные имена разрешаются в имя без ведущего разделителя пространства имён.

Например, <literal>\A\B</literal> разрешается в <literal>A\B</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Относительные имена разрешаются в имя с заменой ключевого слова <literal>namespace</literal>

текущим пространством имён. Префикс <literal>namespace\</literal> удаляется,

если имя встречается в глобальном пространстве имён. Например,

имя <literal>namespace\A</literal> внутри пространства имён <literal>X\Y</literal> разрешается

в <literal>X\Y\A</literal>. То же имя в глобальном пространстве имён разрешается

в <literal>A</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

В полных именах первый сегмент имени преобразовывается с учётом текущей таблицы

импорта класса или пространства имён. Например, если пространство имён <literal>A\B\C</literal>

импортировано как <literal>C</literal>, то имя <literal>C\D\E</literal> преобразуется

в <literal>A\B\C\D\E</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

В полных именах, если не применялось правило импорта, текущее пространство имён добавляется к имени.

Например, имя <literal>C\D\E</literal> внутри пространства имён <literal>A\B</literal>

разрешится в <literal>A\B\C\D\E</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

Неполные имена преобразовываются с учётом текущей таблицы импорта

и типа элемента. То есть имена как у классов преобразовываются с учётом таблицы импорта классов или пространств имён,

имена функций — с учётом таблицы импорта функций, а константы — таблицы импорта

констант. Например, при записи <literal>use A\B\C;</literal>, вызов <literal>new C()

</literal> разрешается в <literal>A\B\C()</literal>. Аналогично, при

записи <literal>use function A\B\foo;</literal> вызов <literal>foo()</literal> разрешается

в <literal>A\B\foo</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

В начало неполных имён, если не применялось правило импорта и имя относится к элементу

с именем как у класса, добавляется текущее пространство имён. Например,

имя класса в выражении <literal>new C()</literal> внутри пространства имён <literal>A\B</literal> разрешится

в имя <literal>A\B\C</literal>.

</simpara>

</listitem>

<listitem>

<simpara>

В неполных именах, если не применялось правило импорта и имя относится к функции или константе,