Including Files with include()

Including Files with include()

The include() statement enables you to incorporate other files (usually other PHP scripts) into your PHP documents. PHP code in these included files will then be executed as if it were part of the main document. This is useful for including code libraries within multiple pages.

Say you create a really useful function. Without the include() 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 you pasted it into and make the changeover and over again. The include() statement saves you from such a chore. You can add your newly created function to a single document, such as myinclude.php 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 13.1 creates a simple PHP script that uses include() to incorporate and output the contents of a file.

Listing 13.1. Using include()

 1: <?php 2: include("myinclude.php"); 3: ?>

The include() statement in Listing 13.1 incorporates the document myinclude.php, the contents of which you can see in Listing 13.2.

Listing 13.2. The File Included in Listing 13.1

 1: I have been included!!

Put the contents of Listing 13.1 in a file named test_include.php, and the contents of Listing 13.2 in a file named myinclude.php. Place both files in your web server document root. When you access test_include.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 Listing 13.3, we amend the contents of myinclude.php, so that code is executed in the included file.

Listing 13.3. An Include File Containing PHP Code

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

Put the contents of Listing 13.3 in a file called myinclude2.php and change the value of the included file in test_include.php, to point to this new file. Place both these files in your web server document root. Now, when you access test_include.php through your web browser, the output on the screen is

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

The only way we would see the number 8 is if the code for adding 4 and 4 were executed as PHP, and it was.

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 Listings 13.4 and 13.5, we include a file and assign its return value to a variable.

Listing 13.4. Using include() to Execute PHP and Assign the Return Value

 1: <?php 2: $addResult = include("returnvalue.php"); 3: echo "The include file returned ".$addResult; 4: ?>

Listing 13.5. 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 13.4 in a file named test_returnvalue.php; put the contents of Listing 13.5 in a file named returnvalue.php. Place both of these files in your web server document root. When you access test_returnvalue.php tHRough your web browser, the output is

The include file returned 8.

Just as the string suggests on line 5 of Listing 13.5, anything outside the PHP block will not be displayed, if there is a PHP block present in the included file.

Using include() Within Control Structures

If you want to use an include() statement within a conditional statement, it will be treated like any other codethe file will be included only if the condition is met. For example, the include() statement in the following fragment will never be called:

$test = "1"; if ($test == "2") {    include("file.txt"); // won't be included }

If you use an include() statement within a loop, the file will literally be included each time the loop iterates. Listing 13.6 illustrates this concept by using an include() statement in a for loop. The include() statement references a different file for each iteration.

Listing 13.6. Using include() Within a Loop

 1: <?php 2: for ($x = 1; $x<=3; $x++) { 3:    $incfile = "incfile".$x.".txt"; 4:    echo "Attempting to include ".$incfile."<br/>"; 5:    include("$incfile"); 6:    echo "<br/>"; 7: } 8: ?>

Save the contents of Listing 13.6 in a file called loopy_include.php and place it in the document root of the web server, along with 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 13.1.

Figure 13.1. Output of loopy_ include.phd.

Although this code worked just fine, there are some instances in which using the include() function in this manner would not be such a great idea, as you'll see in the next section.

Using include_once()

One of the problems caused by using several different libraries of code within your code is the danger of calling include() twice on the same file. This sometimes happens in larger projects when different library files call include() on a common file.

Including the same file twice often results in repeated declarations of functions and classes, thereby causing the PHP engine great unhappiness.

This situation is remedied by using the include_once() function in place of the include() function. The include_once() function requires the path to an include file and otherwise behaves the same way as the include() function the first time it's called. However, if include_once() is called again for the same file during script execution, the file will not be included again. This makes include_once() an excellent tool for the creation of reusable code libraries!

The include_path Directive

Using include() and include_once() to access your code libraries can increase the flexibility and reusability of your projects. However, there are still headaches to overcome. Portability, in particular, can suffer if you hard-code the paths to included files. Imagine that you create a lib directory and reference it throughout your project:

include_once("/home/user/bob/htdocs/project4/lib/mylib.inc.php");

When you move your project to a new server, you might find that you have to change a hundred or more include paths, if this is hard-coded in a hundred or more files. You can escape this fate by setting the include_path directive in your php.ini file:

include_path .:/home/user/bob/htdocs/project4/lib/

The include_path value can include as many directories as you want, separated by colons (semicolons in Windows). The order of the items in the include_path directive determines the order in which the directories are searched for the named file. The first dot (.) before the first colon indicates "current directory," and should be present. Now, any path used in include() or include_once() can be relative to the value of include_path:

include_once("mylib.inc.php");

When you move your project, you need to change only the include_path directive.

By the Way

PHP also has a require() statement, which performs a similar function to include(), and a require_once() statement.

Anything pulled into your code by require() is executed regardless of a script's flow, and therefore shouldn't be used as part of conditional or loop structures.

Also, be aware that a file included as a result of a require() statement cannot return a value.