include

Syntax

include(subor)

Popis

Príkaz jazyka PHP
Funkcia include a require slúži na vloženie súboru.
Tyto dva příkazy jsou zcela totožné, kromě toho, jak zpracovávají chyby. include() produkuje Warning (varování), zatímco require() skončí s chybou typu Fatal Error. Jinými slovy, require použijte tehdy, chcete-li, aby se při chybějícím souboru zastavilo zpracovávání. include() se tak nechová, skript bude nerušeně pokračovat. Ujistěte se také, že máte v pořádku nastavení include_path.

Pokud se vloží soubor, potom kód v něm obsažený dědí kontext proměnné řádku, kde byl vložen. Všechny proměnné dostupné na tomto řádku volajícího souboru budou (od této chvíle) dostupné i ve volaném souboru.

Príklady

Základní příklad -- include()

vars.php
<?php
$color = 'zelené';
$fruit = 'jablko';
?>

test.php
<?php
echo "Vidím $color $fruit"; // Vidím
include 'vars.php';
echo "Vidím $color $fruit"; // Vidím zelené jablko
?>

Pokud ke vložení dojde uvnitř funkce ve volajícím souboru, potom se všechen kód obsažený ve volaném souboru bude chovat, jako by byl definován uvnitř této funkce -- tedy v rámci kontextu proměnných funkce.

Vkládání uvnitř funkcí

<?php

function foo()
{
global $color;

include 'vars.php';

echo "Vidím $color $fruit";
}

/* vars.php je v kontextu foo(), takže *
* $fruit NENÍ dostupná mimo tento kontext. *
* Naopak $color JE, protože je deklarována *
* jako globální. */

foo(); // Vidím zelené jablko
echo "Vidím $color $fruit"; // Vidím zelené

?>

Při vkládání souboru přejde parsing na začátku souboru z PHP režimu do módu HTML a na jeho konci se vrací zpět do módu PHP. Z tohoho důvodu musí být prováděný PHP kód ve vkládaném souboru uzavřen mezi platnou počáteční a koncovou PHP značku.

Pokud jsou v PHP povoleny "URL fopen wrappery" (což tak implicitně je), můžete specifikovat soubor ke vložení pomocí URL (přes HTTP) namísto lokálního umístění. Pokud přískušný server interpretuje požadovaný soubor jako PHP kód, proměnné mohou být odkazovány pomocí řetězce URL požadavku jako u HTTP GET. Není to úplně totéž jako vložení souboru s děděním kontextu proměnných od rodičovského souboru; skript běží na vzdáleném serveru a výsledek se potom vloží do lokálního skriptu.

include() přes HTTP

<?php

/* Tento příklad předpokládá, že www.example.com je konfigurován k parsování *
* souborů .php a nikoli souborů .txt. Tedy, 'funguje' zde znamená, že *
* proměnné $foo a $bar jsou dostupné uvnitř vkládaného souboru. */

// Nefunguje; file.txt nebyl na www.example.com zpracován jako PHP
include 'http://www.example.com/file.txt?foo=1&bar=2';

// Nefunguje; hledá soubor 'file.php?foo=1&bar=2' v lokálním systému souborů.
include 'file.php?foo=1&bar=2';

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

$foo = 1;
$bar = 2;
include 'file.txt'; // Funguje.
include 'file.php'; // Funguje.

?>

Související informace -- viz také Vzdálené soubory, fopen() a file().

Protože include() a require() jsou speciální jazykové příkazy, pokud se provádějí podmíněně, musíte je uzavřít do bloku.

include() a podmíněné bloky

<?php

// Toto je ŠPATNĚ a (jak bylo řečeno) nebude to fungovat.
if ($condition)
   include $file;
else
   include $other;

// Tohle je SPRÁVNĚ.
if ($condition) {
   include $file;
} else {
   include $other;
}

?>

Obsluha návratů: Uvnitř vkládaného souboru lze provést příkaz return() k ukončení provádění souboru a návrat do volajícího skriptu. Je tedy možné z vložených souborů vracet hodnoty. Můžete vzít hodnotu volání include, jako by to byla normální funkce.

Poznámka: V PHP 3 se return nesmí objevit uvnitř bloku, pokud to není funkční blok; tehdy však se však return() týká této funkce a ne celého souboru.

include() a příkaz return()

return.php
<?php

$var = 'PHP';

return $var;

?>

noreturn.php
<?php

$var = 'PHP';

?>

testreturns.php
<?php

$foo = include 'return.php';

echo $foo; // vypíše 'PHP'

$bar = include 'noreturn.php';

echo $bar; // vypíše 1

?>

$bar má hodnotu 1, protože příkaz include byl úspěšný. Všimněte si rozdílu mezi výše uvedenými příklady. První používá ve vkládaném souboru return(), druhý nikoli. Dalšími způsoby, jak přiřadit hodnotu souboru do proměnné, jsou funkce fopen(), file() a použití include() společně s funkcemi řízení výstupu.

Pozri aj

require, require_once, include_once, readfile, virtual, a include_path