Including Files with include()

Including Files with `include()`

The include() statement enables you to incorporate files into your PHP documents. PHP code in these files can be executed as if it were part of the main document. This can be useful for including library code in multiple pages.

Having created a killer function, your only option until now would have been to paste it into every document that needs to use it. Of course, if you discover a bug or want to add a feature, you would have to find every page that uses the function to make the change. The include() statement can save you from this chore. You can add the function to a single document and, at runtime, read it into any page that needs it. The include() statement requires a single argument: a relative path to the file to be included. Listing 10.1 creates a simple PHP script that uses include() to incorporate and output the contents of a file.

Listing 10.1 `Using include()`

   1: <html>   2: <head>   3: <title>Listing 10.1 Using include()</title>   4: </head>   5: <body>   6: <?php   7: include("listing10.2.php");   8: ?>   9: </body>  10: </html>

The include() statement in Listing 10.1 incorporates the document listing10.2.php, the contents of which you can see in Listing 10.2.

Listing 10.2 The File Included in Listing 10.1

   1: I have been included!!

Put the contents of Listing 10.1 in a file named listing10.1.php, and the contents of Listing 10.2 in a file named listing10.2.php. Place both files in your Web server document root. When you access listing10.1.php through your Web browser, the output on the screen is

 I have been included!!

This might seem strange to you, given that we've included plain text within a block of PHP code. In fact, the contents of an included file are displayed as text by default. If you want to execute PHP code in an included file, you must enclose it in PHP start and end tags. In Listings 10.3 and 10.4, we amend the previous example so that code is executed in the included file.

Listing 10.3 Using the `include()` Statement to Execute PHP in Another File

   1: <html>   2: <head>   3: <title>Listing 10.3 Using include to execute PHP in another file</title>   4: </head>   5: <body>   6: <?php   7: include("listing10.4.php");   8: ?>   9: </body>  10: </html>

Listing 10.4 An Include File Containing PHP Code

   1: <?php   2: print "I have been included!!<BR>";   3: print "But now I can add up... 4 + 4 = ".(4 + 4);   4: ?>

Put the contents of Listing 10.3 in a file named listing10.3.php, and the contents of Listing 10.4 in a file named listing10.4.php. Place both these files in your Web server document root. When you access listing10.3.php through your Web browser, the output on the screen is

 I have been included!! But now I can add up... 4 + 4 = 8

Returning a Value from an Included Document

Included files in PHP can return a value in the same way that functions do. As in a function, using the return statement ends the execution of code within the included file. Additionally, no further HTML is included. In Listings10.5 and 10.6 we include a file and assign its return value to a variable.

Listing 10.5 Using `include()` to Execute PHP and Assign the Return Value

   1: <html>   2: <head>   3: <title>Listing 10.5 Using include() to execute PHP and   4:      assign the return value</title>   5: </head>   6: <body>   7: <?php   8: $addResult = include("listing10.6.php");   9: print "The include file returned $addResult";  10: ?>  11: </body>  12: </html>

Listing 10.6 An Include File That Returns a Value

   1: <?php   2: $retval = (4 + 4);   3: return $retval;   4: ?>   5: This HTML will never be displayed because it comes after a return statement!

Put the contents of Listing 10.5 in a file named listing10.5.php, and the contents of Listing 10.6 in a file named listing10.6.php. Place both of these files in your Web server document root. When you access listing10.5.php through your Web browser, the output is

 The include file returned 8

Using `include()` Within Control Structures

You can use an include() statement in a conditional statement, and the referenced file is read only if the condition is met. For example, the include() statement in the following fragment will never be called:

 $test = false; if ($test) { include("a_file.txt"); // won't be included }

If you use an include() statement within a loop, it's replaced with the contents of the referenced file each time the include() statement is called. This content is executed for every call. Listing 10.7 illustrates this concept by using an include() statement in a for loop. The include() statement references a different file for each iteration.

Listing 10.7 Using `include()` Within a Loop

   1: <html>   2: <head>   3: <title>Listing 10.7 Using include() within a loop</title>   4: </head>   5: <body>   6: <?php   7: for ( $x = 1; $x<=3; $x++ ) {   8:    $incfile = "incfile$x".".txt";   9:    print "Attempting include $incfile<br>";  10:    include( "$incfile" );  11:    print "<p>";  12: }  13: ?>  14: </body>  15: </html>

When Listing 10.7 is run, it includes the content of three different files: "incfile1.txt", "incfile2.txt", and "incfile3.txt". Assuming that each of these files simply contains a confirmation of its own name, the output should look like Figure 10.1.

Figure 10.1. Output of Listing 10.7.

graphics/10fig01.gif