require()

Het require() statement vervangt zichzelf met de gespecificeerde file, bijna gelijk als de C preprocessor's #include werkt.

Als "URL fopen wrappers" zijn enabled in PHP (dit zijn ze in de default distributie) dan kun je met require() ook een URL gebruiken in plaats van een lokaal bestand. Zie Remote files en fopen() voor meer informatie.

Het is belangrijk om te weten dat wanneer er een bestand wordt geinclude()ed of gerequire()ed, de parser uit PHP komt en naar HTML mode gaat voordat het bestand wordt toegevoegd, en weer start met de PHP mode aan het einde van het bestand. Om deze reden moet alle code in het bestand dat als PHP code moet worden ge?erpreteerd moet worden omvat met geldige PHP start en end tags.

require() is eigenlijk geen functie in PHP; maar het is een taal constructie. Er gelden andere dingen voor constructies dan voor functies. Bijvoorbeeld is het niet mogelijk om require() een return waarde mee te geven. Als je toch probeert een return waarde te lezen uit een require() aanroep, krijg je een parse error.

In tegenstelling tot include() leest require() altijd het bestand in, zelfs als de regel waarop de require call staat nooit wordt uitgevoerd.. Als je een bestand conditioneel wilt laden, gebruik dan de include() functie. Een conditioneel statement heeft geen invloed op een require(). Als een regel waarop de require() staat niet wordt uitgevoerd, dan zal de code in de required file ook niet worden uitgevoerd.

Gelijksoortig hebben loop structuren geen effect op het gedrag van require(). Hoewel de code in de required file nog steeds in de loop staat, wordt het require() statement zelf maar ? keer uitgevoerd.

Al dit betekend dat je niet kunt verwachten dat require() binnen een loop structuur per iteratie een ander besstand kan invoegen. Om zoiets te doen, kun je het include() statement gebruiken.


require ('header.inc');

Als een bestand is gerequire()ed, dan zal de code de inhoud van de variabele scope overnemen zoals deze was op het punt van de require(). Alle variabelen die beschikbaar waren in de aanroepende file, zullen ook beschikbaar zijn de in aangeroepen file. Als de require() optreed in een functie in de aanroepende file, dan zal de code die zich in het bestand dat ge-required wordt zich gedragen alsof deze in de functie waarin require() wordt aangeroepen.

Als de require()ed file wordt opgeroepen over HTTP met gebruikmakend van de fopen wrappers, en als de target server dit bestand kan interpreteren als PHP code, dan mogen er variabelen worden meegegeven aan de require()ed file met gebruik maken als een HTTP GET regel (zie voorbeeld). Dit is niet precies hetzelfde als require()ing een bestand en het laten overnemen van de variabele scope van de aanroepende file. In dit geval wordt het script uitgevoerd op de remote server en het resultaat van het script zla opgenomen worden in het lokale script.


/* Dit voorbeeld gaat er van uit dat someserver is geconfigureerd om
 * .php bestanden uit te voeren, maar .txt file niet. Ook betekent
 * 'werkt' hier dat de variabelen $vareen en $vartwee beschikbaar
 * zijn binnen de require()ed file. */

/* Werkt niet; file.txt werd niet geparsed door someserver. */
require ("http://someserver/file.txt?varone=1&vartwo=2");

/* Werkt niet; er wordt gekeken naar het bestand 'file.php?varone=1&vartwo=2'
 * op het huidige bestandssysteem. */
require ("file.php?varone=1&vartwo=2");               

/* Werkt. */
require ("http://someserver/file.php?varone=1&vartwo=2"); 

$varone = 1;
$vartwo = 2;
require ("file.txt");  /* Werkt. */
require ("file.php");  /* Werkt. */

In PHP 3 is het mogelijk een return waarde terug te geven vanuit een require()ed bestand, zo lang dat statement optreed binnen de globale scope van het require()ed bestand. Het mag niet optreden binnen een blok (d.w.z. binnen accolades ({}). In PHP 4, is deze mogelijkheid echter niet meer aanwezig. Als je dit toch wilt, zie dan de include() functie.

Zie ook include(), require_once(), include_once(), readfile(), en virtual().