include
(PHP 4, PHP 5, PHP 7, PHP 8)
Вираз include включає та виконує зазначений файл.
Документація нижче також відноситься до виразу require
Файли включаються виходячи зі шляху зазначеного файлу, або, якщо шлях не вказано, використовується шлях, вказаний у директиві include_path. Якщо файл не знайдено в include_path include спробує перевірити директорію, в якій знаходиться поточний скрипт і поточну робочу директорію перед тим, як видати помилку. Конструкція include видасть E_WARNING, если не сможет найти файл; поведение отлично отrequire, який видасть E_ERROR
Обратите внимание, что иincludeиrequire видають додаткову помилку рівня E_WARNING, якщо до файлу неможливо отримати доступ, перед тим, як видати останню помилку рівня **E_WARNING** або **E_ERROR**соответственно.
Якщо шлях вказаний - абсолютний (починається з літери диска або з \ у Windows або з в Unix/Linux системах) або щодо поточної директорії (починається з или .. . include_path буде проігноровано взагалі. Наприклад, якщо ім'я файлу починається з ../, парсер шукатиме в батьківській директорії запитаний файл.
Для додаткової інформації про те, як PHP обробляє файли та шляхи, що включаються, дивіться документацію для директиви include_path
Коли файл вмикається, його код успадковує ту ж область видимості змінних, як і рядок, де сталося включення. Всі змінні, доступні на цьому рядку у файлі, що включають, будуть також доступні у файлі, що включається. Проте всі функції та класи, оголошені у файлі, що включається, мають глобальну область видимості.
Приклад #1 Простий приклад include
Якщо включення відбувається всередині функції файлу, тоді весь код, що міститься в файлі, буде поводитися так, ніби він був визначений всередині цієї функції. Тобто він буде в тій же області видимості змінних цієї функції. Винятком до цього правила є магічні константи, які виконуються парсером перед тим, як відбувається увімкнення.
Приклад #2 Увімкнення функції
Коли файл увімкнеться, парсинг у режимі PHP-коду припиняється і перемикається в режим HTML на початку вказаного файлу і продовжується знову наприкінці. З цієї причини будь-який код всередині файлу, який повинен бути виконаний як код PHP, повинен бути укладений в коректні теги початку та кінця PHP-коду
Якщо "обгортки URL include" включені в PHP, ви можете також вказати файл для включення через URL (за допомогою HTTP або інших обробників, що підтримуються - дивіться Підтримувані протоколи та обгортки для списку протоколів замість локального шляху. Якщо цільовий сервер інтерпретує вказаний файл як код PHP, змінні можуть бути передані до файлу, що включається за допомогою рядка URL-запиту при використанні HTTP GET. Це зовсім не те саме, що включення файлу та успадкування батьківської області видимості; скрипт виконується на віддаленому сервері, і результат потім включається до локального скрипту.
Приклад #3 Прикладincludeчерез HTTP
Увага
Попередження безпеки
Видалені файли можуть бути оброблені на віддаленій стороні (залежно від розширення файлу і того, що віддалений сервер виконує скрипти PHP чи ні), але це все одно має робити коректний скрипт PHP, тому що він буде оброблений вже на локальному сервері. Якщо файл з віддаленого сервера має бути оброблений і відображений його результат, набагато ефективно скористатися функцією readfile() В іншому випадку слід дотримуватися особливої обережності, щоб убезпечити віддалений скрипт для отримання коректного та бажаного коду.
Смотрите также разделВидалені файли, функції fopen() і file() для додаткової інформації.
Обробка значень, що повертаються: оператор include повертає значення FALSE у разі виникнення помилки та видає попередження. Успішні включення, поки це не перевизначено у файлі, повертають значення . Можливо виконати вираз return всередині файлу, щоб завершити процес виконання в цьому файлі і повернутися до виконання файлу, що включає. Крім того, можливо повернути значення з файлів, що включаються. Ви можете отримати значення включення, якби викликали звичайну функцію. Хоча це неможливо при включенні видаленого файлу, тільки якщо виведення видаленого файлу не містить коректні теги початку та кінця PHP коду (Так само, як і локальний файл). Ви можете визначити необхідні змінні всередині цих тегів і вони будуть представлені залежно від того, який файл вимкнено.
Так какinclude - це спеціальна мовна конструкція, круглі дужки не є обов'язковими навколо аргументу. Будьте уважні при порівнянні значення, що повертається.
Приклад #4 Порівняння значення, що повертається при include
Приклад #5 Вирази includeиreturn
$barимеет значение , т.к. Увімкнення файлу відбулося успішно. Зауважте різницю між прикладами зверху. Перший використовує return всередині файлу, тоді як другий не використовує. Якщо файл не може бути увімкнений, повертається false і виникає E_WARNING
Якщо у файлі, що вмикається, визначені функції, вони можуть бути використані в головному файлі незалежно від того, чи були вони оголошені до return чи після. Якщо файл вмикається двічі, PHP видасть фатальну помилку, оскільки функції вже було визначено. Рекомендується використовувати include_once замість того, щоб перевіряти, чи був файл вже включений.
Інший шлях "включити" PHP-файл у змінну - це захопити висновок за допомогою функцій контролю виведеннявместе сincludeНаПриклад:
Приклад #6 Використання буферизації виводу для включення файлу PHP у рядок
Для того, щоб включати файли автоматично в скрипти, зверніть увагу на конфігураційні директиви auto_prepend_file і auto_append_fileв php.ini.
Зауваження: Оскільки це мовна конструкція, а не функція, її не можна викликати як змінну функцію або передавати як іменований аргумент
Смотрите такжеrequire require_once include_once get_included_files() readfile() virtual() і include_path