Including other files

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's 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.

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!

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.

Copyright ©2015 Paul Hudson. Follow me: @twostraws.