Приглашаем посетить
Техника (find-info.ru)

Section 4.16.  Including Other Files

Previous
Table of Contents
Next

4.16. Including Other Files

One of the most basic operations in PHP is including one script in another, thereby sharing functionality. This is done by using the include keyword, 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 PHP drops out of PHP mode whenever it includes another file, then reenters 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";
    ?>

PHP includes a file only 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 your script absolutely needs a particular file, PHP also has the require keyword, which, if called on a file that does not exist, will halt script execution with a fatal error. Any file you include in your script will most likely be essential, so it is usually best to use require.

Section 4.16.  Including Other Files

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 even if the conditional statement evaluated to false. This is no longer the case in PHP 5: files are included only when the conditional statement they are in (if any) evaluates to true.


The most common way to use include files is as storage for common functions, object definitions, and layout code. For example, if your site uses the same header HTML on every page, you can start each of your pages with this:

    include 'header.php';

That way, whenever you want to change the header of your site, you just need to edit header.php. 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 lowercase filenames for everything. On Windows, filenames for inclusion are case-insensitive in PHP 5, meaning that including BAR.php and bar.php will include the same file.

When you try to include or require a file, PHP first checks the directory in which the script is running, and if it doesn't find it there, it looks in its include path. The include path is defined in your php.ini file using the include_path directive.

Section 4.16.  Including Other Files

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; 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, so it's best to use include_once( ). Failing that, the get_included_files( ) and get_required_files( ) functions tell you the names of the files you have already includedthey are actually the same function internally, so you can use either one.



Previous
Table of Contents
Next