include()

Instrukcja include() służy do wczytania i wykonania kodu z określonego pliku w trakcie wykonywania skryptu.

Poniższa dokumentacja dotyczy także instrukcji require(). Obydwie instrukcje są identyczne w każdym szczególe, z wyjątkiem obsługi błędów. include() generuje błąd typu Warning, podczas gdy require() generuje błąd Fatal Error. Innymi słowy, funkcji require() używa się, by zatrzymać przetwarzanie skryptu, gdy brakuje jakiegoś pliku. Jeżeli zostanie użyta funkcja include(), to w powyższej sytuacji skrypt będzie przetwarzany dalej. Proszę pamiętać o właściwym ustawieniu dyrektywy include_path.

Kiedy plik zostanie wczytany instrukcją include(), zawarty w nim kod dziedziczy zasięg zmiennych po linii, w której znajdowała się instrukcja wczytania. Każda zmienna dostępna w linii z instrukcją include() będzie dostępna we wczytywanym pliku od miejsca wczytania naprzód.

Przykład 16-3. Podstawowe wykorzystanie include() vars.php <?php $kolor = 'zielone'; $owoc = 'jabłko'; ?> test.php <?php echo "Jedno $kolor $owoc"; // Jedno include 'vars.php'; echo "Jedno $kolor $owoc"; // Jedno zielone jabłko ?>

Jeśli instrukcja wczytania znajduje się wewnątrz deklaracji funkcji, to cały kod zawarty w pliku wczytywanym będzie zachowywał się, jakby był zdefiniowany wewnątrz tej funkcji. Znaczy to, że odziedziczy zasięg zmiennych po tej funkcji.

Przykład 16-4. Wczytywanie wewnątrz funkcji <?php function foo() { global $kolor;     include 'vars.php';     echo "Jeden $kolor $owoc"; } /* vars.php znajduje się w zasięgu foo(), więc * * $owoc NIE jest dostępny poza zasięgiem tej  * * funkcji. Natomiast $kolor jest dostępny,    * * ponieważ został zadeklarowany w zasięgu     * * globalnym.                                  */ foo();                    // Jedno zielone jabłko echo "A $kolor $owoc";   // Jedno zielone ?>

Na początku wczytywanego pliku parsowanie wychodzi z trybu PHP do trybu HTML i wraca do trybu początkowego na końcu. Z tego powodu każdy kod wewnątrz wczytywanego pliku będzie wykonany jako kod PHP, o ile będzie zawarty w ważnych znacznikach początku i końca kodu PHP.

Jeśli "URL fopen wrappers" są włączone w PHP (takie jest domyślne ustawienie) można podać nazwę pliku do wczytania używając adresu URL (przez protokół HTTP lub innym obsługiwanym sposobem - zajrzyj do Dodatek L aby zapoznać się z listą obsługiwanych protokołów), zamiast podawać ścieżkę lokalną. Jeśli podany w adresie serwer interpretuje plik docelowy jako kod PHP, można do tego skryptu przekazać zmienne w taki sam sposób jak przy metodzie GET protokołu HTTP. Ściśle mówiąc, nie jest to to samo, co wczytywanie pliku lokalnego; jest to wykonanie pliku na zdalnym serwerze i wklejenie rezultatu jego działania do skryptu wywołującego. W tym przypadku, rzecz jasna, zasięg globalny zmiennych nie obejmuje pliku wczytywanego tą metodą.

Przykład 16-5. include() i protokół HTTP <?php /* Przykład ten zakłada, że serwer www.example.com jest tak skonfigurowany, * że wykonuje skrypty w plikach .php natomiast nie wykonuje skryptów w plikach * .txt. Pojęcie 'działa', znaczy tutaj, że zmienne $foo i $bar są dostępne * we wczytywanym pliku                                                       */ // Nie działa: file.txt nie jest traktowany jak skrypt php include 'http://www.example.com/file.txt?foo=1&bar=2'; // Nie działa: PHP będzie szukać pliku o nazwie 'file.php?foo=1&bar=2' // w lokalnym systemie plików include 'file.php?foo=1&bar=2'; // Działa. include 'http://www.example.com/file.php?foo=1&bar=2'; $foo = 1; $bar = 2; include 'file.txt';  // Działa. include 'file.php';  // Działa. ?>

Patrz także Korzystanie ze zdalnych plików, fopen() i file().

Ponieważ include() i require() są specialnymi konstrukcjami językowymi, muszą być umieszczone w instrukcji grupującej, aby mogły działać w instrukcji warunkowej.

Przykład 16-6. include() i instrukcja warunkowa <?php // Ten kod jest NIEPOPRAWNY i nie zadziała zgodnie z oczekiwaniami. if ($warunek)     include $plik; else     include $inny; // Natomiast ten kod jest POPRAWNY. if ($warunek) {     include $plik; } else {     include $inny; } ?>

Obsługa zwracanych wartości: można wywołać instrukcję return() wewnątrz wczytywanego pliku, aby zakończyć jego wykonywanie i powrócić do pliku wywołującego. Można też zwracać wartości z wczytywanych plików, co upodabnia wczytywanie plików do wykorzystywania funkcji.

Przykład 16-7. include() i wyrażenie return() return.php <?php $var = 'PHP'; return $var; ?> noreturn.php <?php $var = 'PHP'; ?> testreturns.php <?php $foo = include 'return.php'; echo $foo; // wyświetla 'PHP' $bar = include 'noreturn.php'; echo $bar; // wyświetla 1 ?>

Zmienna $bar ma wartość 1, ponieważ wczytywanie pliku zakończyło się powodzeniem. Proszę zauważyć istotną różnicę pomiędzy powyższymi przykładami. Pierwszy używa instrukcji return() wewnątrz wczytywanego pliku, natomiast drugi nie. Inne możliwości "wczytania" plików do zmiennych to fopen(), file() lub przez użycie include() razem z Funkcjami Kontroli Wyjścia.

Patrz także require(), require_once(), include_once(), readfile(), virtual(), i include_path.