include()

Оператор include() подключает и вычисляет специфицированный файл.

Нижеследующая документация применима также к require(). Эти две конструкции идентичны во всём, кроме обработки облома. include() выводит Warning!, а require() выдаёт Fatal Error. Иначе говоря, используйте require(), если вы хотите, чтобы отсутствие файла останавливало процессинг страницы. include() не работает таким образом, скрипт продолжит выполнение. Не забудьте также о соответствующей установке include_path.

Когда файл подключён/included, содержащийся в нём код наследует область видимости переменной строки, на которой возникло подключение. Любые переменные, доступные на этой строке в вызывающем файле, будут доступны в вызываемом файле, вперёд от этой точки.

Пример 1. Базовый пример include()
vars.php
$color = 'green';
$fruit = 'apple';
test.php
echo "A $color $fruit"; // A

include 'vars.php';

echo "A $color $fruit"; // A green apple

Если подключение возникает внутри функции в вызываемом файле, то весь код, содержащийся во включаемом файле, будет работать так, как если бы он был определён внутри. Так что он будет следовать области видимости переменной.

Пример 2. Подключение внутри функций
function foo()
{
global $color;

    include 'vars.php';

    echo "A $color $fruit";
}

/* vars.php находится в области видимости foo(), поэтому *
 * $fruit НЕ доступна вне это области видимости *
 * $color доступна, поскольку мы объявили её как глобальную. */

foo();                    // A green apple
echo "A $color $fruit";   // A green

Когда файл подключается, разбор переходит из режима PHP в режим HTML в начале целевого файла и вновь продолжает после конца. Исходя из этого, любой код внутри файла назначения, который должен выполняться как PHP-код, обязан быть заключён в правильные стартовый и конечный тэги РНР.

Если "URL fopen-оболочки" включены в PHP (как в конфигурации по умолчанию), вы можете специфицировать файл, подключаемый с использованием URL (через HTTP), вместо локального pathname. Если целевой сервер интерпретирует целевой файл как PHP-код, переменные могут передаваться в подключаемый файл с использованием URL-строки запроса, как в HTTP GET. Строго говоря, это не то же самое, что подключение файла и наследование им области видимости переменных родительского файла; ведь скрипт работает на удалённом сервере, а результат затем подключается в локальный скрипт.

Предупреждение!

Windows-версия PHP в настоящее время не поддерживает доступ к удалённым файлам с помощью этой функции, даже если allow_url_fopen включена.

Пример 3. include() через HTTP
/* Здесь предполагается, что www.example.com сконфигурирован для разбора .php *
 * файлов, а не .txt файлов. Также 'Works' здесь означает, что переменные *
 * $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';

$foo = 1;
$bar = 2;
include 'file.txt';  // Работает.
include 'file.php';  // Работает.

Смотрите также Удалённые файлы, fopen() и file().

Поскольку include() и require() являются специальными конструкциями языка, вы обязаны заключить их в блок операторов, если это внутри условного блока.

Пример 4. include() и условные блоки
// Это НЕПРАВИЛЬНО, и не будет работать так, как ожидается.
if ($condition)
    include $file;
else
    include $other;


// Это КОРРЕКТНО.
if ($condition) {
    include $file;
} else {
    include $other;
}

Обработка возвращает: можно выполнить оператор return() внутри подключённого файла, чтобы прервать обработку этого файла и возвратиться в скрипт, вызвавший его. Также можно возвращать значения из подключённых файлов. Вы можете принять значение вызова include как обычно.

Примечание: в PHP 3 возвращаемое значение может не появиться внутри блока, если это не блок функции; в этом случае return() применяется к этой функции, а не ко всему файлу.

Пример 5. include() и оператор return()
return.php
$var = 'PHP';
return $var;
noreturn.php
$var = 'PHP';
testreturns.php
$foo = include 'return.php';
echo $foo; // печатает 'PHP'
$bar = include 'noreturn.php';
echo $bar; // печатает 1

$bar имеет значение 1, поскольку подключение было успешным. Обратите внимание на отличия в примерах. Первый использует return() внутри подключённого файла, а другие - нет.

Пример 6. Использование буферизации вывода для включения PHP файлов
$string = get_include_contents('somefile.php');

function get_include_contents($filename) {
    if (is_file($filename)) {
        ob_start();
        include $filename;
        $contents = ob_get_contents();
        ob_end_clean();
        return $contents;
    }
    return false;
}
Пример 7. Универсальное использование включения файла без привязки к текущему каталогу
include $_SERVER['DOCUMENT_ROOT']."/lib/sample.lib.php";
Пример 8. Включение файла изображения
header('Content-type: image/jpeg');
header('Content-Disposition: inline;');

include '/some_image.jpg';
echo 'This file was provided by example@user.com.';

Другие способы чтения файлов в переменные возможны с помощью функций: fopen(), file() или путём использования include() вместе с Функциями управления выводом.

Смотрите также require(), require_once(), include_once(), readfile(), virtual() и include_path.

Все функции операторы
Описание на ru2.php.net
Описание на php.ru