include

Оновлено: 11.05.2023

(PHP 4, PHP 5, PHP 7, PHP 8)

Вираз include включає та обробляє вказаний файл.

Документація, наведена нижче, також відноситься до вимог.

Файли включаються на основі вказаного шляху до файлу або, якщо його не вказано, на основі include_path. Якщо файл не знайдено у include_path, include нарешті перевірить власний каталог викликаючого скрипта і поточний робочий каталог перед тим, як завершити роботу. Якщо не вдасться знайти файл, конструкція include видасть попередження E_WARNING; така поведінка відрізняється від поведінки require, яка видає попередження E_ERROR.

Зауважте, що обидва включають і вимагають згенерувати додаткові E_WARNING, якщо до файлу неможливо отримати доступ, перед тим, як згенерувати остаточне E_WARNING або E_ERROR, відповідно.

Якщо визначено шлях - абсолютний (починаючи з літери диска або \ у Windows, або / у системах Unix/Linux) або відносний до поточного каталогу (починаючи з . або ..) - include_path буде проігноровано повністю. Наприклад, якщо ім'я файлу починається з ../, синтаксичний аналізатор шукатиме потрібний файл у батьківському каталозі.

Більш детальну інформацію про те, як PHP обробляє файли, що включаються, і шлях до них, можна знайти в документації до include_path.

Коли файл включається, код, який він містить, успадковує область видимості змінних рядка, в якому відбувається включення. Будь-які змінні, доступні у цьому рядку у файлі, що викликає, будуть доступні у файлі, що викликається, з цього моменту. Однак, усі функції та класи, визначені у включеному файлі, мають глобальну область видимості.

Приклад #1 Базовий приклад включення

vars.php
<?php

$color = 'green';
$fruit = 'apple';

?>

test.php
<?php

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

include 'vars.php';

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

?>

Якщо включення відбувається всередині функції у викликаючому файлі, то весь код, що міститься у викликаючому файлі, поводитиметься так, ніби він був визначений всередині цієї функції. Тобто, він буде слідувати за областю видимості змінних цієї функції. Винятком з цього правила є магічні константи, які обчислюються синтаксичним аналізатором до того, як відбудеться включення.

Приклад #2 Включення у функції

<?php

function foo()
{
    global $color;

    include 'vars.php';

    echo "A $color $fruit";
}

/* vars.php is in the scope of foo() so     *
* $fruit is NOT available outside of this  *
* scope.  $color is because we declared it *
* as global.                               */

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

?>

При включенні файлу синтаксичний аналіз переходить з режиму PHP в режим HTML на початку цільового файлу і відновлюється знову в кінці. З цієї причини будь-який код у цільовому файлі, який має виконуватися як PHP-код, має бути укладений у правильні початкові та кінцеві теги PHP.

Якщо в PHP увімкнено опцію "URL include wrappers", ви можете вказати файл для включення за допомогою URL-адреси (через HTTP або іншу підтримувану обгортку - див. список протоколів у розділі Підтримувані протоколи та обгортки) замість локального шляху. Якщо цільовий сервер інтерпретує цільовий файл як PHP-код, змінні можуть бути передані до включеного файлу за допомогою рядка запиту URL, як у випадку з HTTP GET. Це, строго кажучи, не те ж саме, що включення файлу і успадкування ним області видимості змінних батьківського файлу; скрипт фактично виконується на віддаленому сервері, а його результат потім включається в локальний скрипт.

Приклад #3 включення через HTTP

<?php

/* This example assumes that www.example.com is configured to parse .php
* files and not .txt files. Also, 'Works' here means that the variables
* $foo and $bar are available within the included file. */

// Won't work; file.txt wasn't handled by www.example.com as PHP
include 'http://www.example.com/file.txt?foo=1&bar=2';

// Won't work; looks for a file named 'file.php?foo=1&bar=2' on the
// local filesystem.
include 'file.php?foo=1&bar=2';

// Works.
include 'http://www.example.com/file.php?foo=1&bar=2';
?>

Віддалений файл може бути оброблений на віддаленому сервері (залежно від розширення файлу і того, чи працює на ньому PHP чи ні), але він все одно повинен створити правильний PHP-скрипт, тому що він буде оброблений на локальному сервері. Якщо файл з віддаленого сервера має бути оброблений там і тільки виведений, то краще використовувати функцію readfile(). В іншому випадку слід подбати про безпеку віддаленого скрипта, щоб він створював правильний і потрібний код.

Див. також статті Віддалені файли, fopen() і file() для отримання відповідної інформації.

Обробка повернень: включення повертає FALSE у разі невдачі і видає попередження. Успішне включення, якщо воно не перевизначене включеним файлом, повертає 1. Можна виконати інструкцію повернення всередині інклюдованого файлу, щоб завершити обробку у цьому файлі і повернутися до скрипту, який його викликав. Також можна повертати значення з включених файлів. Ви можете отримати значення виклику include так само, як і для звичайної функції. Однак це неможливо при включенні віддалених файлів, якщо вивід віддаленого файлу не має правильних початкових і кінцевих тегів PHP (як і у випадку з будь-яким локальним файлом). Ви можете оголосити необхідні змінні в цих тегах, і вони будуть введені в будь-якому місці, де було включено файл.

Оскільки include є спеціальною мовною конструкцією, дужки навколо її аргументу не потрібні. Будьте обережні, порівнюючи значення, що повертаються.

Приклад #4 Порівняння значення, що повертається функцією include

<?php
// won't work, evaluated as include(('vars.php') == TRUE), i.e. include('1')
if (include('vars.php') == TRUE) {
    echo 'OK';
}

// works
if ((include 'vars.php') == TRUE) {
    echo 'OK';
}
?>

Приклад #5 include та оператор return

return.php
<?php

$var = 'PHP';

return $var;

?>

noreturn.php
<?php

$var = 'PHP';

?>

testreturns.php
<?php

$foo = include 'return.php';

echo $foo; // prints 'PHP'

$bar = include 'noreturn.php';

echo $bar; // prints 1

?>

$bar має значення 1, оскільки включення пройшло успішно. Зверніть увагу на різницю між наведеними вище прикладами. У першому з них використовується return у включеному файлі, а у другому - ні. Якщо файл не може бути включено, повертається false і видається E_WARNING.

Якщо у включеному файлі визначені функції, вони можуть бути використані в основному файлі незалежно від того, чи знаходяться вони перед поверненням або після нього. Якщо файл буде включено двічі, PHP видасть фатальну помилку, оскільки функції вже було оголошено. Рекомендується використовувати include_once замість того, щоб перевіряти, чи файл вже було включено, і умовно повертати всередині включеного файлу.

Інший спосіб "включити" PHP-файл у змінну - перехопити вивід за допомогою функцій керування виводом з include. Наприклад:

Приклад #6 Використання буферизації виводу для включення PHP-файлу в рядок

<?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;
}

?>

Щоб автоматично включати файли в скрипти, дивіться також параметри конфігурації auto_prepend_file і auto_append_file в файлі php.ini.

Примітка: Оскільки це мовна конструкція, а не функція, її не можна викликати за допомогою функцій-змінних або іменованих аргументів.