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ą.

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.

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.

Notatka: W PHP 3 instrukcja return() może pojawić się w bloku instrukcji tylko wówczas, jeśli znajduje się on wewnątrz funkcji. W takim przypadku, oczywiście, return() odnosi się do tej funkcji a nie do całego pliku.

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.

User Contributed Notes


Script to determine the location of a file that I am trying to include.



a. What is the path of the file in relation to the current directory, and assuming that the file name is relative to the scripts location?



include(FindScriptRelativeToCurentDirectory(dirname(realpath (__FILE__))) . "relpath/myIncFile.php");



where "relpath/myIncFile.php" is the name of the file that you are trying to include relative to your script (the script where the include() resides).



The path returned is terminated with a slash.



b. What is the path of the file in relation to the current directory, and assuming that the file name is relative to the doc root?



include(FindScriptRelativeToCurentDirectory("myFile", true, true));



the second parameter tells the function that myFile is relative to the doc root (instead of the executing script's path), and the second parameter tells the function that myFile contains a file name (it is not just a path).



/*

**** Get relative path of this file (relative to current directory)

$scriptPathOrName              - either the path or name of the script that you are trying to find.

$scriptPathIsRelativeToDocRoot - if this is false, it is assumed that $scriptPathOrName is relative

                                 to the script currently executing. Otherwise, it is relative to

                                 doc root.

$thisIsAFileName               - If true, then $scriptPathOrName includes the file name.

                                 Otherwise, it is just a path.

*/

function FindScriptRelativeToCurentDirectory($scriptPathOrName, $scriptPathIsRelativeToDocRoot=false, $thisIsAFileName=false) {



$currentPath = realpath ('.');

$commonPathPtr = 0;



/* Find the character used to separate dir names (backslash in windows, forwardslash in Linux, etc.) */

$dirChar = "";

for ($i=0; $i < strlen($currentPath ); $i++) {

    if ($currentPath{$i} == '/' or $currentPath{$i} == '\\') {

        $dirChar = $currentPath{$i};

        break;

    }

}



/* If script is relative to doc root, combine the two */

if ($scriptPathIsRelativeToDocRoot) {

    $rootPath = $_SERVER['DOCUMENT_ROOT'];



    if($rootPath{strlen($rootPath)-1} != $dirChar) {

        $rootPath .= $dirChar;

    }

    if ($scriptPathOrName{0} == '/' or $scriptPathOrName{0} == '\\') {

        $scriptPathOrName = substr($scriptPathOrName, 1, strlen($scriptPathOrName) - 1);

    }

    $scriptPathOrName = $rootPath . $scriptPathOrName;

}



/* because you may developing in different systems that where you are going to deploy,

   there may be a mix of backslashes and forwardslashes when combining the root path

   with a script name. We need to insure consistency. */

if ($dirChar == '/') {

    $scriptPathOrName = str_replace ('\\', $dirChar, $scriptPathOrName);

} else {

    $scriptPathOrName = str_replace ('/', $dirChar, $scriptPathOrName);

}



/* Make sure that the paths end on slash */

if($currentPath{strlen($currentPath)-1} != $dirChar) {

    $currentPath .= $dirChar;

}

if($scriptPathOrName{strlen($scriptPathOrName)-1} != $dirChar) {

    $scriptPathOrName .= $dirChar;

}



/* Find out where it is that the two paths deviate */

for ($i=0; $i < strlen($currentPath) && $i < strlen($scriptPathOrName); $i++) {

    if (strtolower($currentPath{$i}) != strtolower($scriptPathOrName{$i})) {

        break;

    }

    if ($currentPath{$i} == $dirChar) {

        $commonPathPtr = $i;

    }

}



/* Navigate up the current directory to the node where the two directory trees were the same */

$relativePath = "." . $dirChar;

for (; $i < strlen($currentPath); $i++) {

    if ($currentPath{$i} == $dirChar) {

        $relativePath .= ".." . $dirChar;

    }

}



/* Now append the directory down from the common node to where this file is at */

if ($commonPathPtr < strlen($scriptPathOrName)-1) {

    $relativePath .= substr($scriptPathOrName, $commonPathPtr+1, strlen($scriptPathOrName)-$commonPathPtr-1);

}



/* Remove trailing slash if this was a filename */

if ($thisIsAFileName) {

    $relativePath= substr($relativePath, 0, strlen($relativePath) - 1);

}



return($relativePath);

}


In the documentation for include, they say that your included file will inherit the scope of the line where it was included. In other words, if you include a file within a function, it has access to all variables within that function, but no non-global variables outside that function.



I had a class definition, and in one of the methods I included a php file. However, when I tried to access any of the properties of the class, it didn't work.



Example:



class MyClass {

    var $SomeProperty;



    // Constructor

    function MyClass () {

        $this->SomeProperty = "A string of words";

    }



    function DoSomething() {

        $foo = "bar";

        include("include_file.php");

    }

}



The contents of "include_file.php" are:



<?php

echo($foo);

echo($this->SomeProperty);

?>



Now, if you instantiate that class and call the DoSomething method, you will see:



bar

Notice: Undefined variable: this in /path/to/include_file.php on line 3



What a disappointment. So what are the options? The only ones I can come up with are:



a) redefine all properties of the class inside the function as function-specific variables before including your file and remove the "this->" from your included file.



b) remove the <?php and ?> lines from the file and use the file function to import the file contents into an array. Then implode the array and call eval on the string.



Both solutions are pretty awful. (a) is potentially a hell of a lot of work, and with (b) you can't ever break out of the php tags to write some plain html (all html will have to be echoed) - and I bet (b) is way slower than just including a file, too.



If anyone has any ideas about how to better get around this issue, please post it.


To expand on marco_ at voxpopuli-forum dot net's and redeye at cs-aktuell dot de's notes, here's a function to securely include files with direct output or a return.



<?php



/* The DOC_ROOT constant should set on it's own just fine. If you would like to set a sub-directory, just tack it on to the end.

For example:

    define ( 'DOC_ROOT', $_SERVER["DOCUMENT_ROOT"]."/inc_dir" );

    define ( 'DOC_ROOT', $_SERVER["DOCUMENT_ROOT"]."/stuff/inc_dir" );



NOTE: Leave the trailing slash off. It shouldn't make a difference mostly, but just in case ;)

*/



define ( 'DOC_ROOT', $_SERVER["DOCUMENT_ROOT"] );



/* Fill this with all forbidden files. It only requires a filename, not the directory.*/

$badFiles = array (

    'database.inc.php'

);

/* Fill this with all forbidden directories. Please provide the absolute path, with DOC_ROOT starting the path. Please see the example already in the array.*/

$badDirs = array (

    DOC_ROOT.'/private',

);



/**

* Provides a secure method of including files.

*

* @param string $file  the file to include

* @param bool $return  wether or not to output directly or return via output buffering

* @return bool|string  false on failure, true on success without $return=true, string

*                      with file with $return=true

* @author James "necrotic" Logsdon <necrotic at gmail dot com>

* @version 1.0

*/

function secure_include ( $file, $return = false )

{

    global $badFiles, $badDirs;

    if ( !is_array ( $badFiles ) OR !isset ( $badFiles ) ) $badFiles = array();

    if ( !is_array ( $badDirs ) OR !isset ( $badDirs ) ) $badDirs = array();



    // Get path information

    $realPath = realpath ( $file );

    $dirName  = dirname ( $realPath );

    $baseName = basename ( $realPath );



    if ( !$realPath )

    {

        // The file wasn't found by realpath, so we have a 404.

        echo '<h1>404 Not Found</h1> We could not find the file you tried to load.';

        return false;

    }

    else if ( in_array ( $baseName, $badFiles ) OR

        in_array ( $dirName, $badDirs ) OR

        !strstr ( $realPath, DOC_ROOT ) )

    {

        // Oh crap! It's a forbidden file!

        echo '<h1>403 Forbidden</h1> You do not have permission to view this file.';

        return false;

    }

    else if ( !$return )

    {

        // We're safe, include away!

        include_once ( $file );

        return true;

    }

    else

    {

        ob_start();

        include_once ( $file );

        $page = ob_get_contents();

        ob_end_clean();

        return $page;

    }

}



/*

* Usage

* secure_include ( 'file.txt' ); // returns true if exists, outputs error or file

* secure_include ( 'file.txt', true ); // returns the file if exists, outputs error if not or 403 Forbidden

*/



?>


Need a way to simpify the passing of may variables to include files?  Working on a project where you don't have access to every script involved?  Is an eval or some other routine killing your access to $GLOBALS?



Let us call this aproach Scope Linking.

-----------------------------

We can "hijack" the $_SESSION superglobal (or any other) and use it for our own purposes (assuming it's not in use already).  HERE'S HOW:



-----------------------------

Main file (sample1.php):

<?php

   include ('sample2.php');



   $_SESSION['var3'] = array();



   $var2 =& $_SESSION['var2'];

   $var3 =& $_SESSION['var3'];



   $var1 = "Origional var1";

   $var2 = "Origional var2";

   $var3 = array('house'=>'blue','car'=>'tired','jet'=>'scripted');



   $results = &Funky();



   echo "------------------------<br>\n";

   echo "Sample1 Script Output<br>\n";

   echo "Var1: $var1<br>\n";

   echo "Var2: $var2<br>\n";

   echo "Var3: ${var3['house']} ${var3['car']} ${var3['jet']}<br>\n";

   echo "------------------------<br>\n";

?>

-----------------------------



-----------------------------

Included file (sample2.php):

<?php

function &Funky()

{

   foreach ($_SESSION as $name=>$val )

   {

      $$name =& $_SESSION["$name"];

   }

   echo "------------------------<br>\n";

   echo "Sample2 Script Output<br>\n";

   echo "Var1: $var1<br>\n";

   echo "Var2: $var2<br>\n";

   echo "Var3: ${var3['house']} ${var3['car']} ${var3['jet']}<br>\n";



   $var1 = 'Second var1';

   $var2 = 'wow, both ways! var2 rulez!';

}

?>

-----------------------------



OUTPUT:

------------------------

Sample2 Script Output

Var1:

Var2: Origional var2

------------------------

Sample1 Script Output

Var1: Origional var1

Var2: wow, both ways! var2 rulez!

------------------------



YES this means predeclairing your variables by referencing them to $_SESSION elements unless you prefer to use the longer form:

<?php   $_SESSION['var2'] = "here's var2"; ?>



if you want all $GLOBALS has to offer you can be way less specific (grab it all, slower & only a copy):

<?php 

   foreach ($GLOBALS as $name=>$val )

   {

      $_SESSION["$name"] = $val;

   }

?>

To see what you have access to, paste this in at the point you're interested in:

-----------------------------

<?php

    if(isset($_SESSION))

    {

        foreach ($_SESSION as $key=>$val)

        {

            echo "$key -- $val <br>\n";

        } 

    }

?>

-----------------------------



P. S. Because it's a superglobal you can get away without using compact, but compact() & extract() are another options to crack this nut.


I just discovered a "gotcha" for the behavior of include when using the command line version of php. 



I copied all the included files needed for a new version of a program into a temporary directory, so I could run them "off to the side" before they were ready for release into the live area. One of the files with a new version (call it common.inc.php for this example) normally lives in one of the directories in the include path. But I did not want to put the new version there yet! So I copied common.inc.php into my temporary directory along with the others, figuring that the interpreter would find it there before it found it in the include directory, because my include path has a . at the beginning. When I tested it, everything was fine.



But then I setup a cron job to run the script automatically every day. In the crontab I placed the full path of the script. But when it ran, it included the old version of my common.inc.php file out of the include directory. Interestingly, the other include files that only existed in the temporary directory were included fine. 



Evidently AFTER the include path is searched, the directory in which the main script lives is searched as well. So my temporary installation almost worked fine, except for the lack of the small change I had made in the common file introduced a bug.



To make it work I use a shell script to start my php script. It contains a cd command into the temporary directory, then starts the php script.



So "current directory" (the . in the include path) for a command line script is really the current directory you are in when executing the script. Whereas it means the directory in which the script lives when executing under apache.



I hope this helps save someone else the hours it took me to figure out my problem!



David