PHP Basics – Part 8 :: Control Structures – Part 4

File-Inclusion Statements

Efficient programmers are always thinking in terms of ensuring reusability and modularity. The most prevalent means for ensuring such is by isolating functional components into separate files and then reassembling those files as needed. PHP(PHP Scripting Language) offers four statements for including such files into applications, each of which is introduced here.

The include() Statement

The include() statement will evaluate and include a file into the location where it is called. Including a file produces the same result as copying the data from the file specified into the location in which the statement appears. Its prototype follows:

include(/path/to/filename)

Like the print and echo statements, you have the option of omitting the parentheses when using include(). For example, if you want to include a series of predefined functions and configuration variables[configuring php], you could place them into a separate file (called init.inc.php, for example), and then include that file within the top of each PHP script, like this:

<?php
include "/usr/local/lib/php/wjgilmore/init.inc.php";
?>

You can also execute include() statements conditionally. For example, if an include() statement is placed in an if statement, the file will be included only if the if statement in which it is enclosed evaluates to true. One quirk regarding the use of include() in a conditional is that it must be enclosed in statement block curly brackets or in the alternative statement enclosure. Consider the difference in syntax between the following two code snippets. The first presents incorrect use of conditional include() statements due to the lack of proper block enclosures:

<?php
if (expression)
include ('filename');
else
include ('another_filename');
?>

The next snippet presents the correct use of conditional include() statements by properly enclosing the blocks in curly brackets:

<?php
if (expression) {
include ('filename');
} else {
include ('another_filename');
}
?>

One misconception about the include() statement is the belief that because the included code will be embedded in a PHP execution block, the PHP escape tags aren’t required. However, this is not so; the delimiters (escape tags) must always be included. Therefore, you could not just place a PHP command in a file and expect it to parse correctly, such as the one found here:

echo "this is an invalid include file";

Instead, any PHP statements must be enclosed with the correct escape tags, as shown here:

<?php
echo "this is an invalid include file";
?>

Tip Any code found within an included file will inherit the variable scope of the location of its caller. If the PHP configuration directive allow_url_fopen is enabled, it’s possible to reference a remote file within an include() statement. If the resident server (choosing a web host) is PHP-enabled, any variables found within the included file can be parsed by passing the necessary key/value pairs as would be done in a GET request, like this:

include "http://www.wjgilmore.com/index.html?background=blue";

Ensuring a File Is Included Only Once

The include_once() function has the same purpose as include() except that it first verifies whether the file has already been included. Its prototype follows:

include_once (filename)

If a file has already been included, include_once() will not execute. Otherwise, it will include the file as necessary. Other than this difference, include_once() operates in exactly the same way as include(). The same quirk pertinent to enclosing include() within conditional statements also applies to include_once().

Requiring a File

For the most part, require() operates like include(), including a template into the file in which the require() call is located. Its prototype follows:

require (filename)

However, there are two important differences between require() and include().

• First, the file will be included in the script in which the require() construct appears, regardless of where require() is located. For instance, if require() is placed within an if statement that evaluates to false, the file would be included anyway.
• Second important difference is that script execution will stop if a require() fails, whereas it may continue in the case of an include(). One possible explanation for the failure of a require() statement is an incorrectly referenced target path.

Tip A URL can be used with require() only if allow_url_fopen is enabled, which by default it is.

Ensuring a File Is Required Only Once

As your site grows, you may find yourself redundantly including certain files. Although this might not always be a problem, sometimes you will not want modified variables in the included file to be overwritten by a later inclusion of the same file. Another problem that arises is the clashing of function names should they exist in the inclusion file. You can solve these problems with the require_once() function. Got it? NO? Get in the field fellas. Have some experience. It will be a lot easier that way.

Its prototype follows:

require_once (filename)

The require_once() function ensures that the inclusion file is included only once in your script. After require_once() is encountered, any subsequent attempts to include the same file will be ignored. Other than the verification procedure of require_once(), all other aspects of the function are the same as for require().

Control Structures – Part 3 <-> Revision