Multiple File PHP Scripts

Regardless of the reasons, inclusion of external files is accomplished through the include, include_once, require, and require_once PHP statements. As you may suspect, of these four statements only the include and require statements actually differ with any great significance, and it is those differences that I'll focus on. First, let's discuss how each of the two flavors work.

NOTE The only difference between the include/require and include_once/require_once statements is how many times a given file will actually be loaded. When the include_once/require_once statements are used, the file cannot be loaded or executed multiple times. If an attempt is made to load a file twice using one of these two methods, it will be ignored. Because it is unacceptable to define the same function multiple times within a script, these functions allow the developer to include a script as needed without having to check whether it has been previously loaded.

The general syntax of both the include and require statements are as follows:

include "file_to_load.php";
include_once "file_to_load.php";

or

require "file_to_load.php";
require_once "file_to_load.php";

Note that for every file inclusion function previously listed, the file to load can be a string constant or a variable containing the name of the file.

NOTE If URL wrappers are enabled in PHP (see Chapter 20, "Working with the File System," and Chapter 21, "Network I/O"), the filename provided to the include statement can be a HTTP address of the file to be loaded.

As I mentioned earlier, it is good practice to separate functions and code that are used in multiple scripts into a separate file. Following that logic, I'll assume that a PHP file exists called library.inc, which contains the is_leapyear() function defined in Listing 1.19. Note that although this file is designed to be "included" rather than directly executed by PHP, it still conforms to all the rules of a normal PHP script. This means that all PHP code must be in appropriate tags, and so on. Note that non-PHP files (such as HTML files) may also be included; they will be dumped into the output as you would expect.

Assuming that library.inc is in the same directory as the actual script, you could use your is_leapyear() function that exists within the library.inc file, as shown in Listing 1.24:

Listing 1.24. Using include to Load Files in PHP

<?php

    include ('library.inc');     // Parentheses are optional 
    $leap = is_leapyear(2003);

?>

NOTE In most practical situations, files that are included into PHP scripts are not in the same directory as the script that actually requires them. Often, all the includable files are stored in a directory that is then designated part of the PHP include file search path. When a file is requested to be included by a PHP script, PHP first checks the current directory for the file followed by the include file path before returning an error.

Likewise, the require statement may also be used to include the file, as shown in Listing 1.25:

Listing 1.25. Using require to Load Files in PHP

<?php

    require ('library.inc');     // Parentheses are optional
    $leap = is_leapyear(2003);

?>

If both statements will allow the current script to execute the code in a separate file, what is the difference between the two? There are two major differences: the first is the capability to return values and the second is under what circumstances the requested file is loaded. When an include statement is used, PHP delays the actual loading of the requested file until the script reaches the point of executing the include statement and replaces the include statement with the contents of the file. Conversely, in the case of the require statement, the require statement is replaced with the contents of the requested file regardless of whether the require statement (and thus the contents of the file) would have executed in the normal progression of the script.

That is all fine, but what exactly does it mean to return a value from an external file? Consider the code shown in Listing 1.26, which we'll assume is stored in the file test.inc and its associated script includetest.php:

Listing 1.26. Behavior of Files Included Using include

<?php

    /* test.inc file */
    echo "Inside the included file<BR>";

    return "Returned String";

    echo "After the return inside the include<BR>";

?>

<?php

    /* includetest.php file */
    echo "Inside of includetest.php<BR>";

    $ret = include ('test.inc');

    echo "Done including test.inc<BR>";
    echo "Value returned was '$ret'";

?>

When includetest.php is executed, what is the result? In this case, the result would be the following:

Inside of includetest.php
Inside the included file
Done including test.inc
Value returned was 'Returned String'

As you can see, not only are external files useful for storing libraries of common PHP functions, they can actually be PHP "functions" when using the include statement. Note that when the return statement was executed from within your includetest.php file, the execution of the remainder of the file terminated.

NOTE The capability to return values from external files is limited only to the include and include_once statements. The require and require_once statements cannot be used in this fashion.