Multiple File PHP Scripts
It is always good practice to make your scripts as modular as possible, designing your functions in such a way that they can be used in other PHP scripts. In this respect, and as you accumulate an ever-growing library of functions, the need to organize them becomes more and more paramount. In PHP, this organization is accomplished by separating your scripts into multiple files and including them when appropriate. Furthermore, by storing sensitive static information such as database login information in separate files, they can be safely placed outside the Web tree of the server and thus be inaccessible by the public.
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.
include "file_to_load.php"; include_once "file_to_load.php";
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.
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); ?>
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'"; ?>
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.