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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: a124543dd3f6b1e5567b07420d23899e582514dc 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> включает и оценивает код файла как PHP-код.
 </simpara>
 <simpara>
  Документация текущего раздела также относится к выражению <function>require</function>.
 </simpara>
 <simpara>
  Файлы включаются на основе заданного пути к файлу или, если путь не указали,
  на основе путей в директиве <link linkend="ini.include-path">include_path</link>.
  Перед выдачей ошибки выражение <literal>include</literal> проверит директорию текущего скрипта,
  в который включается файл, и текущую рабочую директорию, если PHP не нашёл файл
  в списке путей директивы <link linkend="ini.include-path">include_path</link>.
  Выражение <literal>include</literal> выдаст ошибку уровня <constant>E_WARNING</constant>,
  если не найдёт файл; поведение отличается от выражения <function>require</function>,
  которое выдаст фатальную ошибку <constant>E_ERROR</constant>.
 </simpara>
 <simpara>
  Обратите внимание, при недоступности файла для чтения оба выражения выдадут дополнительную ошибку
  уровня <constant>E_WARNING</constant> перед выдачей окончательной
  ошибки уровня <constant>E_WARNING</constant> выражением <literal>include</literal>
  или ошибки уровня <constant>E_ERROR</constant> выражением <literal>require</literal>,
  которые возникают, когда PHP не находит файл.
 </simpara>
 <simpara>
  PHP проигнорирует директиву <link linkend="ini.include-path">include_path</link>,
  если указали абсолютный путь (который начинается с буквы диска,
  или с обратного слеша <literal>\</literal> в Windows и с прямого слеша <literal>/</literal>
  в Unix- и Linux-системах) или путь относительно текущей директории (который начинается
  с символа <literal>.</literal> или символов <literal>..</literal>).
  Например, парсер будет искать запрошенный файл в родительской директории,
  если название файла начинается с <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.magic">магические константы</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>
  PHP разрешает вместо локального пути указывать файлы для включения по URL-адресу,
  если разрешили <link linkend="ini.allow-url-include">работу URL-обёрток с include-выражениями</link>.
  Файлы включают по HTTP-протоколу или через другие обработчики, которые поддерживает язык.
  Список протоколов, которые поддерживаются PHP, приводит страница «<xref linkend="wrappers"/>».
  Переменные передают в файл, который включается с удалённого сервера, в строке запроса URL-адреса
  аналогично передаче аргументов методом GET по протоколу HTTP, если целевой удалённый сервер
  интерпретирует целевой файл как PHP-код. Включение файла с удалённого сервера отличается
  от включения файла, который наследует родительскую область видимости файла, в который включается;
  скрипт выполняется на удалённом сервере, а результат затем включается в локальный скрипт.
 </simpara>
 <para>
  <example>
   <title>
    Пример включения вывода, который сгенерировал скрипт удалённого сервера,
    выражением <literal>include</literal> через HTTP-запрос
   </title>
   <programlisting role="php">
<![CDATA[
<?php

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

// Не сработает; файл 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';

// Сработает: удалённому скрипту будут доступны переменные $foo и $bar
include 'http://www.example.com/file.php?foo=1&bar=2';

?>
]]>
   </programlisting>
  </example>
 </para>
 <warning>
  <title>Предупреждение безопасности</title>
  <para>
   Локальный сервер ожидает, что удалённый сервер создаст и вернёт допустимый PHP-код,
   поскольку скрипт обрабатывается на локальном сервере,
   даже если удалённый сервер работает на PHP и обработал файл на основе расширения.
   Вывод только результата обработки файла на удалённом сервере лучше получить
   вызовом функции <function>readfile</function>,
   а при включении PHP-кода из файла на удалённом сервере потребуется соблюдать
   повышенную осторожность и проверять, чтобы удалённый сервер создал корректный и безопасный код.
  </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>,
  как и с локальными файлами. Переменные, которые объявили внутри PHP-тегов,
  включатся в текущий скрипт в месте включения файла.
 </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
-->