PHP DevCenter
oreilly.comSafari Books Online.Conferences.


Multiple File PHP Scripts
Pages: 1, 2

Returning Values

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:


$returnval = include '';

echo "The file returned a value of '$returnval'<br />";

$returnval = include '';

echo "The file returned a value of '$returnval'<br />";


return 'testing';

echo "Hello, world!<br />";

The result of the above code executing would be:

The file returned a value of 'testing'

Hello, world!

The file 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 and 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 or 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 require and require_once statements.

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 or 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 include_once, 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.

Valuable Online Certification Training

Online Certification for Your Career
Earn a Certificate for Professional Development from the University of Illinois Office of Continuing Education upon completion of each online certificate program.

PHP/SQL Programming Certificate — The PHP/SQL Programming Certificate series is comprised of four courses covering beginning to advanced PHP programming, beginning to advanced database programming using the SQL language, database theory, and integrated Web 2.0 programming using PHP and SQL on the Unix/Linux mySQL platform.

Enroll today!

Sponsored by: