Multiple File PHP Scripts
Pages: 1, 2
At times, it may be beneficial to return a value from within the include statement back to the original calling script. To accomplish this, you may simply place a return statement within the include file but outside of any functions defined within the included file. The returned value will be the result value of the include statement that initiated the inclusion of the file, as shown below:
<?php $returnval = include 'includeme.inc'; echo "The file includeme.inc returned a value of '$returnval'<br />"; $returnval = include 'includeanother.inc'; echo "The file includeanother.inc returned a value of '$returnval'<br />"; ?>
<?php return 'testing'; ?>
<?php echo "Hello, world!<br />"; ?>
The result of the above code executing would be:
The file includeme.inc returned a value of 'testing'
The file includeanother.inc returned a value of '1'
Note that if the included file returns no value the include statement will return true upon success or false upon failure.
Ensuring Files Are Only Included Once
In the above script, you'll notice that we used the include statement to include the same file over and over, each time producing a different result. Sometimes, such as when the file desired to be included as a function definition within it, it is important that the file be included once and only once. Although there are ways to ensure this with a standard include statement PHP provides the means to accomplish this very cleanly by using the statement
include_once instead of simply include. The
include_once statement behaves identically to its sister statement
include with the single difference that PHP will not include the file multiple times. It is recommended that this version of the include statement be used in situations where included files contain function declarations or other code that should not be executed numerous times.
A Note on Errors Occurring with Include Files
One important thing to note regarding the
include_once statements is how PHP handles errors that occur either loading them, or during the process of executing the code within them. In the event of an error during an include statement's execution, PHP will generate a error of type
E_NOTICE and continue execution of the script. How this error is presented to the user depends on the configuration settings of PHP. If the included file is critical to the script's operation, you'll need to use the require statement described below.
Forcing Files to Be Included
As I've discussed, errors that occur during the inclusion or executions of included files using the
include_once statements will cause the trigger of an
E_NOTICE error and return false. Because this error is not considered fatal by PHP scripts, the desired file simply will not be included and script execution will continue. In situations where the code contained within the include file was required, this will produce unpredictable results. To combat this, PHP provides another similar way of including files: the
In versions of PHP prior to 4.0.2, the
require statement behaved differently than its counterpart
include in both the way and at what time files were included. In versions of PHP above 4.0.2,
require now behaves almost identically to
include. The only difference is in what PHP does in case of an error. If an error occurs during the execution of a
require_once statement, it will trigger a fatal error of type
E_ERROR resulting in the entire script execution halting. This behavior is most desired when the included code is critical to the general function of the entire script, such as the setting of critical variables or the definition of functions that are used within the calling script. As with
require_once will ensure that the requested file is included in the PHP script only once.
More to Come
That's just about all there is to the process of including files in your PHP scripts! With this important facet of PHP out of the way, next time I'll be introducing object-oriented programming in PHP and how it can be used to save you time writing and reusing your code.
John Coggeshall is a a PHP consultant and author who started losing sleep over PHP around five years ago.
Return to PHP DevCenter.