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 without include() would be 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 must 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 this into any page that needs it. The include() statement requires a single argument—a relative path to the file to be included. Listing 11.1 creates a simple PHP script that uses include() to incorporate and output the contents of a file .

PHP also provides the require() statement, which is identical to include() in almost every respect. The key difference is that require() halts script execution if the file it seeks to include cannot be found. The include() statement generates a warning if a file cannot be found but does not stop execution.

Listing 11.1 Using `include()`

 1: <!DOCTYPE html PUBLIC
 2:   "-/w3c//DTD XHTML 1.0 Strict//EN"
 3:   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 4: <html>
 5: <head>
 6: <title> Listing 11.1 Using include()</title>
 7: </head>
 8: <body>
 9: <div>
10: <?php
11: include("listing11.2.php");
12: ?>
13: </div>
14: </body>
15: </html>

The include() statement in Listing 11.1 incorporates the document listing11.2.php, the contents of which you can see in Listing 11.2. When run, Listing 11.1 outputs the string "I have been included!!", which might seem strange, given that we have included plain text within a block of PHP code. Shouldn't this cause an error? In fact, the contents of an included file are displayed as HTML 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 11.3 and 11.4, we amend the previous example so that code is executed in the included file .

Listing 11.2 The File Included in Listing 11.1

1: I have been included!!

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

 1: <!DOCTYPE html PUBLIC
 2:   "-//W3C//DTD XHTML 1.0 Strict//EN"
 3:   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 4: <html>
 5: <head>
 6: <title> Listing 11.3 Using include() to Execute PHP in Another File</title>
 7: </head>
 8: <body>
 9: <div>
10: <?php
11: include("listing11.4.php");
12: ?>
13: </div>
14: </body>
15: </html>

Listing 11.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: ?>

Returning a Value from an Included Document

Included files in PHP can return a value in the same way as 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 Listings 11.5 and 11.6, we include a file and assign its return value to a variable.

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

 1: <!DOCTYPE html PUBLIC
 2:   "-//W3C//DTD XHTML 1.0 Strict//EN"
 3:   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 4: <html>
 5: <head>
 6: <title> Listing 11.5 Acquiring a Return Value with include()</title>
 7: </head>
 8: <body>
 9: <div>
10: <?php
11: $addResult = include("listing11.6.php");
12: print "The include file returned $addResult";
13: ?>
14: </div>
15: </body>
16: </html>

Listing 11.6 An Include File That Returns a Value

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

Returning values from included files would work in PHP 3 only if the return statement was contained in a function. The code in Listing 11.6 would cause an error.

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. The include() statement in the following fragment is never called, for example:

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

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

Listing 11.7 Using `include()` Within a Loop

 1: <!DOCTYPE html PUBLIC
 2:   "-//W3C//DTD XHTML 1.0 Strict//EN"
 3:   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 4: <html>
 5: <head>
 6: <title> Listing 11.7 Using include() Within a Loop</title>
 7: </head>
 8: <body>
 9: <div>
10: <?php
11: for ( $x=1; $x<=3; $x++ ) {
12:  $incfile = "incfile".$x.".txt";
13:  print "<p>";
14:  print "Attempting include $incfile<br/>";
15:  include( "$incfile" );
16:  print "</p>";
17: }
18: ?>
19: </div>
20: </body>
21: </html>

When Listing 11.7 is run, it includes the content of three 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 something like this:

Attempting include incfile1.txt
This is incfile1.txt

Attempting include incfile2.txt
This is incfile2.txt

Attempting include incfile3.txt
This is incfile3.txt

`include_once()`

One of the problems caused by using multiple libraries within your code is the danger of calling include() twice on the same file. This can occur in larger projects when different library files call include() on a common file. Including the same file twice often results in the repeated declaration of functions and classes, thereby causing the PHP engine great unhappiness.

The situation is saved by the include_once() statement, which requires the path to an include file and behaves in the same way as include() the first time it is called. If include_once() is called again for the same file during script execution, however, the file is not included again.

This makes include_once() an excellent tool for the creation of reusable code libraries .

PHP also provides the require_once() statement, which behaves in the same way as include_once() with a single exception. If the target file is not encountered when you use require_once(), script execution is halted with a fatal error. If the target file is not encountered when you use include_once(), a warning is generated but script execution continues.

[ Team LiB ]

Including Files with include()

Listing 11.1 Using include()

Listing 11.2 The File Included in Listing 11.1

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