require()

Instrukcja require() służy do wczytania i wykonania skryptu z określonego pliku.

require() wczytuje i wykonuje skrypt z podanego pliku. Szczegółowa informacja odnośnie tego, jak działa wczytywanie opisana jest w dokumentacji dla instrukcji include().

Instrukcje require() i include() są identyczne w każdym szczególe, z wyjątkiem obsługi błędów. W razie niepowodzenia, include() generuje ostrzeżenie (Warning), podczas gdy require() generuje błąd krytyczny (Fatal Error). Innymi słowy, instrukcji require() używa się do wczytywania plików, które są niezbędne do działania skryptu i w przypadku ich braku wykonywanie skryptu musi zostać przerwane. Instukcja include() nie zachowuje się w ten sposób. W jej przypadku, przy braku pliku wykonywanie skryptu będzie kontynuowane. Proszę również pamiętać o właściwym ustawieniu dyrektywy konfiguracyjnej include_path.

Przykład 16-2. Podstawowe przykłady użycia require()


<?php



require 'nagłówek.php';



require $plik;



require ('jakiś_plik.txt');



?>

Więcej przykładów w dokumentacji instrukcji include().

Notatka: Począwszy od PHP 4.0.2, zachowanie instrukcji jest następujące: require() będzie zawsze próbować odczytać plik docelowy, nawet jeśli linia w której ona się znajduje nigdy nie zostanie wykonana. Instrukcja warunkowa nie wpływa na działanie require(). Jednakże, jeśli linia, w której pojawia się require() nie zostaje wykonana, zawartość pliku wczytywanego też nie zostaje wykonana. Podobnie, instrukcje pętli nie wpływają na działanie require(). Chociaż kod zawarty w pliku docelowy wciąż jest podmiotem pętli, require() działa tylko raz.

Ostrzeżenie

PHP w wersji starszej niż 4.3.0, pracujące pod kontrolą systemów Windows, nie obsługują dostępu do zdalnych plików w tej funkcji, nawet jeśli opcja allow_url_fopen jest włączona.

Patrz także include(), require_once(), include_once(), eval(), file(), readfile(), virtual() i include_path.

User Contributed Notes


re: danielm at unb dot br...



$_SERVER['DOCUMENT_ROOT'] is very useful, but it is not available with all web servers. Apache has it; IIS doesn't. 



I use the following to make my PHP applications work in more situations:

<?php

if (!defined("BASE_PATH")) define('BASE_PATH', isset($_SERVER['DOCUMENT_ROOT']) ? $_SERVER['DOCUMENT_ROOT'] : substr($_SERVER['PATH_TRANSLATED'],0, -1*strlen($_SERVER['SCRIPT_NAME'])));

?>



...but even that gets tripped up by symlinks to different mount points, etc. You could substitute realpath($_SERVER['PATH_TRANSLATED']), but that function has been reported not to work on some (Windows) servers. One could use the PATH_TRANSLATED for both servers, but I figure if Apache is going to tell me exactly what I want to know, I should listen.


Something which may not be immediately obvious is that if you use double quotes on the filename, you can use variables to specify the filename, allowing you to do something like this:



<?php

$query = "SELECT filename FROM updates WHERE version>$current ORDER BY version";

$updateresult = mysql_query($query) or exit($query.'<br />'.mysql_error());

while ($updaterow = mysql_fetch_row($updateresult)) {

    require "$updaterow[0]";

}

?>



Drop this in a script on a server and you can push updates to your clients. Obviously, make sure you only run scripts you want to.


NOTE: This function changed how it worked.  In PHP 3 this behaved very differently than it does on PHP 4.  Require used to include and parse the file regardless where the require line was positioned.



For example (PHP3):



<?php

  if(false){ require 'file_does_not_exist.php'; }

?>



That code throw a fatal exception even though it's in a conditional block which evaluates to false.  In PHP 4 the file is never included or parsed, so no exception is thrown.



For example (PHP4)

<?php

  if(false){ require '1_file_does_not_exists.php'; }

  require '2_file_does_not_exists.php';

?>



Stops execution of the script on trying to require the 2nd file...by bypasses the first require.



--JM