PHP kézikönyv
Előző | 16. Fejezet. Vezérlési szerkezetek | Következő

# include()

Az include() beilleszti és feldolgozza a megadott fájlt.

Az alábbiak igazak a require()-ra is. A require() és az include() megegyezik egymással a hibakezelését leszámítva. Az include() nem fatális hibát, figyelmeztetést generál, a require() viszont fatális hibát jelez. Magyarán, ahol az igényelt fájl nemlétekor a futást meg kell szakítani, ajánlott a require(). Az include() nem így viselkedik, a hibától függetlenül a szkript futtatása folytatódik. Bizonyosodj meg, hogy a include_path helyesen van beállítva! Jegyezd meg, hogy a szintaktikai hiba a include()-olt fájlban nem okozza a feldolgozás megszakítását a PHP 4.3.5 verziója előtt, ettől a verziótól kezdve viszont igen.

A beillesztendő fájlokat először az aktuális könyvtárhoz viszonyított include_path-ban keresi, majd az aktuális szkript könyvtárához viszonyított include_path-ban. Például ha az include_path a ., aktuális könyvtár a `/www/`, beillesztetted az `include/a.php`-t amelyben van egy include "b.php" utasítás, a `b.php`-t először a `/www/`-ben keresi, majd a `/www/include/`-ban. Ha a fájlnév ../ karakterekkel kezdődik, csak aktuális munkakönyvtárhoz viszonyított include_path-ban keresi.

A fájl beillesztése során a megadott fájl örökli az include() helyén érvényes változó hatáskört. Bármely változó, amely azon a ponton elérhető, elérhető a beillesztett fájlban is. Ellenben a beillesztett fájlban szereplő függvény- és osztálydefiníciók, globális láthatósággal rendelkeznek.

Példa 16-5. Egyszerű include() példa
`valtozok.php <?php $szin = 'zöld'; $gyumolcs = 'alma'; ?> teszt.php <?php echo "Egy $szin $gyumolcs"; // Egy include 'valtozok.php'; echo "egy $szin $gyumolcs"; // Egy zöld alma ?>`

Függvény belsejében a megadott fájlban szereplő kód úgy fog viselkedni, mintha az magában a függvényben szerepelt volna. Ez azt jelenti, hogy a fájl örökli a változók érvényességi körét.

Példa 16-6. Függvényen belüli beillesztés
`<?php function ize() { global $szin; include 'valtozok.php'; echo "Egy $szin $gyumolcs"; } /* valtozok.php az ize() függvény hatóköréébe esik, * * így a $gyumolcs nem elérhető a főggvényen kívül. * * A $szin igen, mivel globálisnak lett deklarálva. */ ize(); // Egy zöld alma echo "Egy $szin $gyumolcs"; // Egy zöld ?>`

Ha egy fájlt beillesztünk az include()-dal vagy require()-ral, akkor a célfájl elején az elemző kilép a PHP módból HTML módba, majd visszaáll PHP módba a fájl végén. Ennek okán bármely beillesztendő fájlban levő PHP kódot közre kell fogni egy érvényes PHP kezdő- és zárójelöléssel.

Ha a "fopen wrappers" szolgáltatás engedélyezve van (mint például az alapértelmezett konfigurációban), a beillesztendő fájlt megadhatod URL-ként (HTTP-ként vagy más támogatott wrapperként - a protokollok listáját itt találhatod: M Függelék), ahelyett hogy helyi útvonalként adnád meg. Ha a célszerver PHP kódként feldolgozza a fájlt, akkor átadhatsz változókat a hívott fájlnak HTTP GET lekérési formában. Ez nem teljesen ugyanaz, mintha a include()-dal hívott fájl örökölné a helyi változókat, mivel a szkript valójában a távoli szerveren fut le, és a futási eredmény kerül beépítésre a helyi szkriptbe.

Figyelem
A PHP Windows rendszeren futó verziója a 4.3.0-ásnál régebbi változataiban nem támogatja a távoli állomány elérést e függvény használatakor, még akkor sem, ha az allow_url_fopen engedélyezett.

Példa 16-7. include() HTTP-n keresztül
`/* Ezek a példák feltételezik, hogy a szerver be van állítva a .php * fájlok feldolgozására és nincs beállítva a .txt fájlok feldolgozására * A 'működik' azt jelenti, hogy az $ize és $bigyo változók elérhetőek * a hívott fájlban. */ // Nem működik: a file.txt nem kerül feldolgozásra include ("http://szerver/file.txt?ize=1&bigyo=2"); // Nem működik: egy 'file.php?ize=1&bigyo=2' nevű fájlt keres a helyi gépen include ("file.php?ize=1&bigyo=2"); // Működik include ("http://szerver/file.php?ize=1&bigyo=2"); $ize = 1; $bigyo = 2; include ("file.txt"); /* Működik */ incluie ("file.php"); /* Működik */`

A kapcsolodó információkért lásd még: Távoli fájlok eléréséről szóló részt, valamint a fopen() és a file() függvényt!

Mivel az include() és a require() különleges nyelvi elem, kapcsos zárójelekkel kell közrefogni, ha egy feltételes utasításon belül szerepel.

Példa 16-8. include() feltételes blokkon belül
`/*Ez NEM JÓ, és nem a várt eredményt adja */ if ($feltetel) include($file); else include($other); /* Ez a HELYES */ if ($feltetel) { include($file); } else { include($other); }`

return utasítást lehet elhelyezni egy include()-olt fájlban annak érdekében, hogy a kiértékelés ott befejeződjön, és visszaadjon egy értéket a hívó szkriptnek. A visszatérési értéket ugyanúgy használhatod, mint egy közönséges függvénynél. Ez azonban nem lehetséges távoli fájlok beillesztésénél, kivéve akkor, ha a távoli fájl kimenete érvényes kezdő és záró tag-ekkel rendelkezik (mint bármilyen helyi fájl). A szükséges változókat deklarálhatod a tag-ek között, és be lesznek vezetve bármely ponton ahol a fájl beillesztésre került.

Mivel az include() egy speciális nyelvi konstrukció, nem szükséges bezárójelezni az argumenumát. Vigyázz amikor a visszatérítési értékét hasonlítod.

Példa 16-9. Az include visszatérítési értékének hasonlítása
`<?php // nem múködik, mivel include(('vars.php') == 'OK') -ként értelmezi, azaz include('') if (include('vars.php') == 'OK') { echo 'OK'; } // működik if ((include 'vars.php') == 'OK') { echo 'OK'; } ?>`

> Megjegyzés: PHP 3, a return nem jelenhet meg függvény blokkon kívül máshol, amely esetben a függvényből történő visszatérést jelöli.

Példa 16-10. Az include() és a return() utasítás
`return.php <?php $var = 'PHP'; return $var; ?> noreturn.php <?php $var = 'PHP'; ?> testreturns.php <?php $ize = include 'return.php'; echo $ize; // kiírja: 'PHP' $bigyo = include 'noreturn.php'; echo $bigyo; // kiírja: 1 ?>`

$bigyo értéke 1, mert a beillesztés sikeres volt. Figyeld meg a különbséget a két fenti példa között. Az első a return() segítségével visszaadott egy értéket, a második nem. Ha nem tudja beilleszteni a fájlt, `FALSE`-t ad vissza és E_WARNING szintű hibát ad.

Ha a beillesztett fájlban vannak függvénydefiníciók, azokat használni lehet a fő állományban függetelenül attól, hogy a return() előtt vagy után vannak. Ha a fájl kétszer kerül beillesztésre, a PHP 5 fatális hibát ad, mivel a függvények már deklarálva voltak. A PHP 4 nem panaszkodik miattuk a return() után definiált függvények miatt. Ajánlott a include_once() használata, ahelyett hogy a beillesztett fájlban vizsgáld, hogy már be volt-e illesztve és ez esetben return-al kilépjél.

Egy másik módja a PHP fájlok beemelésének a kimenet elfogása a kimenet szabályzó függvények és az include() használatával.

Példa 16-11. PHP file kimenetének stringbe gyűjtése kimenetszabályozás használatával
`<?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; } ?>`

Az automatikus fájlbeillesztéssel kapcsolatban lásd a auto_prepend_file és a auto_append_file `php.ini` konfigurációs beállításokat.

> Megjegyzés: Mivel ez egy nyelvi konstrukció és nem egy függvény, nem hívható meg a változó változók lehetőség felhasználásának segítségével.

Lásd még a require(), require_once(), include_once(), readfile() és virtual() függvényeket!

Előző | Tartalom | Következő
require() | Fel | require_once()