2.6.15 Including other filesThis is NOT the latest copy of this book; click here for the latest version.
One of the most basic operations in PHP is including one script from another, thereby sharing functionality. This is done by using the include keyword, and specifying the filename you want to include.
For example, consider the following file, foo.php:
<?php
print 'Starting foo\n';
include 'bar.php';
print 'Finishing foo\n';
?>
And also the file bar.php:
<?php
print 'In bar\n';
?>
PHP would load the file bar.php, read in its contents, then put it into foo.php in place of the "include 'bar.php'" line. Therefore, foo.php would look like this:
<?php
print 'Starting foo\n';
print 'In bar\n';
print 'Finishing foo\n';
?>
If you were wondering why it only writes in the "In bar" line and not the opening and closing tags, it is because whenever PHP includes another file, it drops out of PHP mode, then re-enters PHP mode as soon as it comes back from the file. Therefore, foo.php, once merged with bar.php, will actually look like this:
<?php
print 'Starting foo\n';
?>
<?php
print 'In bar\n';
?>
<?php
print 'Finishing foo\n';
?>
It has the same effect, but it is a little harder to read!
It is important to note that PHP only includes a file if the include line is actually executed. Therefore, the following code would never include bar.php:
<?php
if (53 > 99) {
include 'bar.php';
}
?>
If you attempt to include a file that does not exist, PHP will generate a warning message. If you find that you write a script that absolutely needs a particular file to be included, PHP also has the require keyword, which, if called on a file that does not exist, will halt script execution with a fatal error. However, the chances of you telling PHP to include a script and it not being a problem if that script cannot be located are slim, so favour require.
Author's Note: In older versions of PHP, require was the equivalent of an unconditional include. If require was placed inside a conditional statement, the file would be included in even if the conditional statement evaluated to false. This is no longer the case in PHP 5.
The most common way to use these include files is as storage for common functions, object definitions, and layout code. For example, if your site always has the same header HTML to it, you can start each of your pages with this:
<?php
include 'header.php';
...[snip]...
That way, whenever you want to change the header of your site, you just need to edit one file. Two more keywords that are likely to be of use are include_once and require_once, which operate in the same way as include and require respectively, with the difference that they will only include a file once, even if you try to include it several times. Include_once and require_once share the same list of "already included" files, but it is important to note that operating systems that are case sensitive, such as Unix, are able to include_once/require_once a file more than once if the programmer uses varying cases for their filenames. For example:
<?php
include_once 'bar.php';
include_once 'BAR.php';
include_once 'Bar.php';
?>
On Unix, that will attempt to include three entirely different files, because Unix is case sensitive. The solution is simple: use lower case filenames for everything! On Windows, the list is case-insensitive in the release version of PHP 5 - if you were an early bird trying out a beta release and have either beta 1 or beta 2 installed, the list is case-sensitive even on Windows and you should upgrade to fix this problem.
Note that if PHP cannot find a file you try to include() or require() in the same directory as the script that is running, it will also look in its standard include path. This is defined in your php.ini file as the include_path directive.
Author's Note: Each time you include a file using include() or require(), PHP needs to compile it. If you're using a code cache this problem is avoided, but if not PHP really does compile the same file several times. That is, if you have various includes for the same file, it will need to be compiled and processed each time - it's best to use include_once(). Failing that, there are two functions called get_included_files() and get_required_file() that will tell you the names of the files you have already included - they are actually the same function internally, so you can use either one.
|
Want to see this stuff in print? PHP in a Nutshell takes the core topics covered here, adds in thousands of edits from the editorial team and myself, and combines them to make an unbeatable reference for PHP programmers at all levels.
My latest book has hundreds more tips on how to use PHP, Apache, and MySQL, plus Perl, Python, shell scripts, performance tuning, and more!
|
