require()

A require() függvény behelyettesítődik a megadott fájllal, pont úgy, mint a C preprocesszor #include-ja.

Ha az "URL fopen wrapper"-ek be vannak kapcsolva (ami az alapbeállítású helyzet), akkor a require() használatakor távoli fájlt is megadhatsz. Lásd a Távoli fájlok kezelése című fejezetet és az fopen() függvényt.

Egy fontos megjegyzés a működésre vonatkozólag, hogy ha egy fájlt berántunk include()-al vagy require()-el, akkor kikerülünk a PHP módból HTML módba a célfájl elején, és visszaáll PHP módba a fájl végén. Ezért, bármely célfájlban levő PHP kódot közre kell fogni egy érvényes PHP kezdő- és zárótag-gel.

A require() valójában nem is egy függvény a PHP-ben, hanem egy nyelvi konstrukció. Ez azt jelenti, hogy más szabályok vonatkoznak rá, mint a függvényekre. Például a require()-re nem vonatkoznak a körbezáró struktúrák korlátozásai. Másfelől, nincs visszatérési értéke; ha megpróbálod kiolvasni a require() hívás visszatérési értékét, a hívás értelmezési hibát (parse error) eredményez.

Az include()-tól eltérőn a require() mindig beolvassa a célfájlt, még akkor is, ha a sor, ahol áll soha nem hajtódik végre. Ha feltételesen szeretnél beemelni egy fájl-t, használd az include()-ot. A feltételes kifejezés nincs hatással a require()-ra. Ennek ellenére, ha a sor, amelyen a require() áll nem hajtódik végre, a célfájlban lévő kód nem is fog lefutni.

Hasonlóan, a ciklusok sem változtatják meg a require() viselkedését. Bár a célfájl kódja a ciklusmagban van, a require() végrehajtása csak egyszer történik meg.

Ez azt jelenti, hogy hiába teszed a require()-t egy ciklus belsejébe azt várva, hogy különböző fájlokat hozzon be minden iterációra. Ha ezt szeretnéd használd az include()-ot. A require-t konstans fájlnevekkel használd:


require ('header.inc');
     

Ha egy fájlt require()-el töltesz be, a kód, amit tartalmaz azt az érvényességi kört örökli, ami a require() hívás sorára vonatkozott. Bármilyen változó, ami azon a soron elérhető, rendelkezésre áll a hívott fájlban. Ha a require() egy függvényben található a hívó fájlban, akkor a hívott fájl minden kódja úgy fog viselkedni, mintha a függvényen belül írtad volna.

Ha a require()-el hívott fájl HTTP-n keresztül érkezik az "fopen wrapper"-ek használatával, és a célszerver feldolgozza a fájlt, mint PHP kódot, átadhatsz változókat a hívott fájlnak HTTP GET lekérési formában. Ez nem ugyanaz, mintha a require()-el 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.


/* 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 $elsovaltozo és $masodikvaltozo
 * változók elérhetőek a behívott fájlban. */

/* Nem működik: a file.txt nem kerül feldolgozásra */
require ("http://szerver/file.txt?elsovaltozo=1&masodikvaltozo=2");

/* Nem működik: egy 'file.php?elsovaltozo=1&masodikvaltozo=2'
 * nevű fájlt keres a helyi rendszeren */
require ("file.php?elsovaltozo=1&masodikvaltozo=2");               

/* Működik */
require ("http://szerver/file.php?elsovaltozo=1&masodikvaltozo=2"); 

$elsovaltozo = 1;
$masodikvaltozo = 2;
require ("file.txt");  /* Működik */
require ("file.php");  /* Működik */

     

A PHP 3-ban van rá lehetőség, hogy egy return-t helyezzünk el a require()-rel behívott fájlba, ha a return a behívott fájl globális részében van. Nem szerepelhet blokkban sem, tehát nem lehet kapcsos zárójelen belül ({}). A PHP 4-ben ezt a lehetőséget megszüntették. Ha szeretnél valami ilyesfélét, akkor nézd meg az include()-ot.

Lásd még: include(), require_once(), include_once(), readfile(), és virtual().