Контролни структури
PHP Manual

include()

Инструкцията include() включва и изпълнява даден файл.

Документацията по-долу се отнася също и за require(). Двете конструкции са идентични във всяко едно отношение, с изключение на начина, по който обработват грешки. Те и двете предизвикват предупреждение, но require() предизвиква също и фатална грешка. С други думи, не се колебайте да използвате require() ако искате липсващ файл да спре изпълнението на скрипта. include() не се държи по този начин, скриптът ще продължи независимо от липсата. Трябва също така да сте сигурни, че имате подходяща стойност за include_path. Трябва да знаете, че грешка в синтаксиса на изисквания файл няма да предизвика спиране на изпълнението във версии на PHP преди PHP 4.3.5. От тази версия нататък - ще го предизвика.

Файловете за включване се търсят първо в пътя за включване (include_path) относително спрямо текущата работна директория, а след това - в директорията на текущия скрипт. Например, ако пътят ви за включване е libraries, текущата работна директория е /www/, вие сте включили include/a.php и там има include "b.php" в този файл, за b.php ще бъде търсено първо в /www/libraries/, а после във /www/include/. Ако името на файла започва с ./ или ../, той ще бъде потърсен само в текущата работна директория.

Когато даден файл бива включван, кодът в него наследява областта на действие на променливите на реда, на който става включването. От този момент нататък, всяка променлива, налична на този ред в извикващия файл ще бъде налична и в извиквания файл. Всички функции и класове, дефинирани във включвания файл, ще имат глобална област на действие.

Example #1 Основен пример за include()

vars.php
<?php

$color 
'зелена';
$fruit 'ябълка';

?>

test.php
<?php

echo "Една $color $fruit"// Една

include 'vars.php';

echo 
"Една $color $fruit"// Една зелена ябълка

?>

Ако включването е вътре във функция в извикващия файл, тогава целият код, който се съдържа в извиквания файл ще се държи сякаш е бил дефиниран вътре в тази функция, така че ще вземе областта на действие на променливите на тази функция. Изключение от това правило са вълшебните константи, които се изчисляват от синтактичния анализатор още преди да се е случило включването (include).

Example #2 Включване във функции

<?php

function foo()
{
    global 
$color;

    include 
'vars.php';

    echo 
"Една $color $fruit";
}

/* vars.php е в обхвата на of foo(), така че *
* $fruit НЕ е налична извън този обхват     *
* $color е налична, защото я декларирахме   *
* като глобална.                            */

foo();                    // Една зелена ябълка
echo "Една $color $fruit";   // Една зелена

?>

Когато даден файл бива включван, анализаторът излиза от режим PHP и влиза в режим HTML в началото на съответния файл и се връща обратно в края. Затова кодът във включвания файл, който трябва да бъде изпълнен като PHP код, трябва да бъде заграден с валидни тагове за начало и край в PHP.

Ако "опаковката URL fopen" е включена в PHP (а тя е в конфигурацията по подразбиране), можете да укажете файла, който да бъде включен, посредством URL (през HTTP или друга поддържана опаковка - вижте List of Supported Protocols/Wrappers за списък на протоколите) вместо локален път към файл. Ако отдалеченият сървър интерпретира дадения файл като PHP код, тогава е възможно да се предават променливи към включвания файл, посредством URL низ-заявка както при HTTP GET. Това не е съвсем същото като да се включва файла и той да наследи променливия обхват на родителския файл; всъщност скриптът се пуска на отдалечения сървър и резултатът чак тогава се включва в локалния скрипт.

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

Windows версиите на PHP преди PHP 4.3.0 не поддържат достъпа до отдалечени файлове посредством тази функция, дори и ако allow_url_fopen е включено.

Example #3 include() през HTTP

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

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

?>

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

Предупреждение за безопасност

Отдалечен файл може да бъде изпълнен на отдалечения сървър (в зависимост от файловото разширение и от това дали отдалеченият сървър стартира PHP или не) но той все пак трябва да даде валиден PHP скрипт, защото той ще бъде обработен на локалния сървър. Ако файлът от отдалечения сървър трябва да бъде обработен там и просто да бъде изведен, то много по-подходяща за тази работа е функцията readfile(). В противен случай трябва да се вземат специални мерки, за да се осигури, че отдалеченият скрипт дава валиден и желан код.

Вж. също Отдалечени файлове, fopen() и file() за информация по темата.

Обработка на връщания: Възможно е да се изпълни инструкция return() във включван файл, за да се прекъсне изпълнението на този файл и да се предаде контролът към извикващия скрипт. Също така е възможно да се връщат стойности от включвани файлове. Можете да вземете стойността на включвания файл, както бихте го направили с нормална функция. Това обаче не е възможно, когато включвате отдалечени файлове, освен ако отдалеченият файл има валидни тагове за начало и край в PHP (както и за локални файлове). Можете да декларирате нужните променливи в тези тагове и те ще бъдат внесени в точката на включването.

Тъй като include() е специална езикова конструкция, употребата на скоби около аргумента й не е необходима. Бъдете внимателни, когато сравнявате връщаната стойност.

Example #4 Сравнение на връщана стойност от include

<?php
// няма да работи, ще се изчисли като include(('vars.php') == 'OK'), т.е. include('')
if (include('vars.php') == 'OK') {
  echo 
'OK';
}

// работи
if ((include 'vars.php') == 'OK') {
  echo 
'OK';
}
?>

Example #5 include() и инструкцията return()

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

?>

$bar има стойност 1, защото включването е било успешно. Отбележете разликата в горните примери. Първият използва return() във включвания файл, докато другият - не. В случай че файлът не може да бъде включен, ще бъде върната стойност FALSE и ще се изведе E_WARNING.

Ако има функции, дефинирани във включвания файл, то те могат да бъдат използвани в главния файл независимо от това дали са преди или след return(). Ако файлът бъде включен повторно, PHP 5 ще изведе фатална грешка, понеже функциите вече са били декларирани, докато PHP 4 няма да се оплаче за функции, дефинирани след return(). Препоръчително е да се използва include_once() вместо да се проверява дали файлът вече е бил включен и да се връща условно във включвания файл.

Друг начин да се "включи" файл от тип PHP в променлива е да се прихване изхода посредством Функциите за контрол на изхода и include(). Например:

Example #6 Буфериране на изхода с цел включване на PHP файл в низ

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

?>

Ако искате да включвате файлове автоматично в скриптовете, вижте също конфигурационните директиви auto_prepend_file и auto_append_file в php.ini.

Забележка: Тъй като това е езикова конструкция а не функция, тя не може да бъде извикана посредством променливи функции

Вж. също require(), require_once(), include_once(), get_included_files(), readfile(), virtual() и include_path.


Контролни структури
PHP Manual