archived-doc-ru/language/control-structures/include.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: ffbe6525350c91d58e1d5b7a52c46c911035c8e0 Maintainer: mch Status: ready -->
<!-- Reviewed: no -->
<sect1 xml:id="function.include" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>include</title>
 <?phpdoc print-version-for="include"?>
 <simpara>
  Выражение <literal>include</literal> включает и выполняет файл.
 </simpara>
 <simpara>
  Документация ниже также относится к выражению <function>require</function>.
 </simpara>
 <simpara>
  Файлы включаются исходя из пути указанного файла, или, если путь не указали,
  PHP ищет файлы по путям, которые определили в директиве
  <link linkend="ini.include-path">include_path</link>. Если файл
  не найден в <link linkend="ini.include-path">include_path</link>,
  выражение <literal>include</literal> попытается проверить директорию,
  в которой находится текущий включающий скрипт,
  и текущую рабочую директорию, перед тем как выдать ошибку. Конструкция
  <literal>include</literal> выдаст ошибку уровня <constant>E_WARNING</constant>,
  если не сможет найти файл; поведение отличается от выражения <function>require</function>,
  которое выдаст фатальную ошибку <constant>E_ERROR</constant>.
 </simpara>
 <simpara>
  Обратите внимание, что и выражение <literal>include</literal>,
  и выражение <literal>require</literal>
  выдают дополнительную ошибку уровня <constant>E_WARNING</constant>,
  если к файлу невозможно получить доступ до выдачи последней ошибки уровня
  <constant>E_WARNING</constant> или <constant>E_ERROR</constant>, соответственно.
 </simpara>
 <simpara>
  Если путь указали — абсолютный (который начинается с буквы диска или с
  обратного слеша <literal>\</literal> в Windows или с прямого слеша <literal>/</literal>
  в системах Unix или Linux) или относительно текущей директории (начинающийся с
  <literal>.</literal> или <literal>..</literal>) —
  выражение <link linkend="ini.include-path">include_path</link> вообще будет проигнорировано.
  Например, если имя файла начинается с <literal>../</literal>,
  парсер будет искать запрошенный файл в родительской директории.
 </simpara>
 <simpara>
  Документация к директиве <link linkend="ini.include-path">include_path</link>
  подробнее рассказывает об обработке языком PHP включаемых файлов и путей.
 </simpara>
 <simpara>
  Когда файл включается, код файл наследует ту же
  <link linkend="language.variables.scope">область видимости переменных</link>,
  что и строка, на которой произошло включение. Переменные, которые доступны на этой строке
  во включающем файле, будут также доступны во включаемом файле.
  Однако у функций и классов, которые объявили во включаемом файле,
  будет глобальная область видимости.
 </simpara>
 <para>
  <example>
   <title>Простой пример <literal>include</literal></title>
   <programlisting role="php">
<![CDATA[
vars.php
<?php

$color = 'зелёное';
$fruit = 'яблоко';

?>

test.php
<?php

echo "Одно $color $fruit"; // Одно

include 'vars.php';

echo "Одно $color $fruit"; // Одно зелёное яблоко

?>
]]>
   </programlisting>
  </example>
 </para>
 <simpara>
  Если файл включается внутри функции включающего файла,
  тогда код, который содержится во включаемом файле, будет вести себя так,
  как будто он его определили внутри этой функции. То есть, код будет в той же области видимости
  переменных этой функции.
  Исключение к этому правилу — <link
  linkend="language.constants.predefined">магические константы</link>, которые
  выполняются парсером перед включением.
 </simpara>
 <para>
  <example>
   <title>Включение внутри функции</title>
   <programlisting role="php">
<![CDATA[
<?php

function foo()
{
    global $color;

    include 'vars.php';

    echo "Одно $color $fruit";
}

/**
 * Файл vars.php в той же области видимости, что и функция foo(),
 * поэтому переменная $fruit НЕ будет доступна за пределами этой области.
 * Переменная $color — доступна, поскольку её объявили глобальной
 */

foo();                     // Одно зелёное яблоко
echo "Одно $color $fruit"; // Одно зелёное

?>
]]>
   </programlisting>
  </example>
 </para>
 <simpara>
  Когда файл включается, парсинг в режиме PHP-кода прекращается и переключается
  в режим HTML в начале указанного файла и продолжается
  снова в конце. Поэтому любой код внутри включаемого файла,
  который должен быть выполнен как код PHP, должен быть заключён в
  <link linkend="language.basic-syntax.phpmode">корректные теги начала и конца PHP-кода</link>.
 </simpara>
 <simpara>
  Если "<link linkend="ini.allow-url-include">обёртки URL include</link>"
  включены в PHP, допускается также указать файл для включения через URL (через HTTP или
  других поддерживающихся обработчиков — смотрите <xref linkend="wrappers"/> для списка
  протоколов) вместо локального пути. Если целевой сервер интерпретирует
  указанный файл как PHP-код, переменные можно передать во включаемый файл
  через строку URL-запроса HTTP-методом GET. Это не то же самое,
  что включение файла и наследование родительской области видимости; скрипт
  выполняется на удалённом сервере, а результат затем включается в локальный скрипт.
 </simpara>
 <para>
  <example>
   <title>Пример <literal>include</literal> через HTTP</title>
   <programlisting role="php">
<![CDATA[
<?php

/**
 * В этом примере предполагается, что адрес www.example.com настроен на обработку
 * файлов .php, но не .txt. Также, «Сработает» здесь означает, что переменные
 * $foo и $bar доступны внутри включаемого файла.
 */

// Не сработает; файл file.txt не обрабатывается адресом www.example.com как PHP-код
include 'http://www.example.com/file.txt?foo=1&bar=2';

// Не сработает; будет искать файл 'file.php?foo=1&bar=2' в
// локальной файловой системе
include 'file.php?foo=1&bar=2';

// Сработает
include 'http://www.example.com/file.php?foo=1&bar=2';

?>
]]>
   </programlisting>
  </example>
 </para>
 <warning>
  <title>Предупреждение безопасности</title>
  <para>
   Удалённые файлы могут быть обработаны на удалённой стороне (в зависимости от
   расширения файла и того, что удалённый сервер выполняет скрипты PHP или нет), но это всё равно
   должно производить корректный скрипт PHP, потому что он затем будет обработан уже на
   локальном сервере. Если файл с удалённого сервера должен быть обработан,
   а его результат только отображён, эффективнее воспользоваться функцией <function>readfile</function>.
   В противном случае требуется соблюдать особую осторожность, чтобы обезопасить
   удалённый скрипт для получения корректного и желаемого кода.
  </para>
 </warning>
 <para>
  Раздел «<link linkend="features.remote-files">Удалённые файлы</link>» и описания
  функций <function>fopen</function> и <function>file</function> дают дополнительную
  информацию.
 </para>
 <simpara>
  Обработка возвращаемых значений: оператор <literal>include</literal> возвращает
  значение <literal>FALSE</literal>, если возникла ошибка, и выдаёт предупреждение. Успешные
  включения, пока это не переопределили во включаемом файле, возвращают значение
  <literal>1</literal>. Допускается выполнять выражение <function>return</function>
  внутри включаемого файла, чтобы завершить процесс выполнения в
  этом файле и вернуться к выполнению включающего файла. Кроме того, возможно вернуть
  значение из включаемых файлов. Можно получить значение включения, как
  если бы вызвали обычную функцию. Хотя это невозможно при включении
  удалённого файла, только если вывод удалённого файла не содержит
  <link linkend= "language.basic-syntax.phpmode">корректные теги начала и конца PHP
  кода</link> (так же, как и локальный файл). Разрешено определять необходимые
  переменные внутри этих тегов и они будут представлены в зависимости от того,
  какой файл был выключен.
 </simpara>
 <para>
  Поскольку выражение <literal>include</literal> — специальная языковая конструкция,
  круглые скобки не обязательны вокруг аргумента. При сравнении
  возвращаемого значения соблюдают осторожность.
  <example>
   <title>Сравнение значения, которое возвращает выражение include</title>
   <programlisting role="php">
<![CDATA[
<?php

// Не сработает, PHP интерпретирует как include(('vars.php') == TRUE), то есть include('1')
if (include('vars.php') == TRUE) {
    echo 'OK';
}

// Cработает
if ((include 'vars.php') == TRUE) {
    echo 'OK';
}

?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  <example>
   <title>Выражения <literal>include</literal> и <function>return</function></title>
   <programlisting role="php">
<![CDATA[
return.php
<?php

$var = 'PHP';

return $var;

?>

noreturn.php
<?php

$var = 'PHP';

?>

testreturns.php
<?php

$foo = include 'return.php';

echo $foo; // выведет 'PHP'

$bar = include 'noreturn.php';

echo $bar; // выведет 1

?>
]]>
   </programlisting>
  </example>
 </para>
 <simpara>
  Значение переменной <literal>$bar</literal> равно <literal>1</literal>, поскольку
  инструкция успешно включила файл. Заметьте разницу между приведёнными примерами.
  В первом записали <function>return</function> внутри включаемого файла, тогда как втором нет.
  Если файл не получается включить, возвращается &false; и возникает
  ошибка уровня <constant>E_WARNING</constant>.
 </simpara>
 <para>
  Если во включаемом файле определили функции, эти функции можно вызывать
  в главном файле независимо от того, объявили ли функции до инструкции
  <function>return</function> или после.
  Если файл включат дважды, PHP выдаст фатальную ошибку, потому что функции
  уже определили.
  Рекомендуется использовать выражение <function>include_once</function> вместо
  проверки включения файла.
 </para>
 <simpara>
  Другой путь «включить» PHP-файл в переменную — захватить
  вывод <link linkend="ref.outcontrol">функциями контроля вывода</link>
  вместе с выражением <literal>include</literal>. Например:
 </simpara>
 <para>
  <example>
   <title>Буферизация вывода и включение файла PHP в строку</title>
   <programlisting role="php">
<![CDATA[
<?php

$string = get_include_contents('somefile.php');

function get_include_contents($filename) {
    if (is_file($filename)) {
        ob_start();
        include $filename;
        return ob_get_clean();
    }
    return false;
}

?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  Обратите внимание на конфигурационные директивы
  <link linkend="ini.auto-prepend-file">auto_prepend_file</link>
  и <link linkend="ini.auto-append-file">auto_append_file</link>
  в файле &php.ini;, чтобы включать файлы в скрипты автоматически.
 </para>

 &note.language-construct;

 <simpara>
  Смотрите также описания функций <function>require</function>,
  <function>require_once</function>, <function>include_once</function>,
  <function>get_included_files</function>, <function>readfile</function>,
  <function>virtual</function> и описание выражения
  <link linkend="ini.include-path">include_path</link>.
 </simpara>
</sect1><!-- 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
-->