PHP Manual
Prev | Chapter 11. Control Structures | Next

# require_once()

The require_once() statement replaces itself with the specified file, much like the C preprocessor's `#include` works, and in that respect is similar to the require() statement. The main difference is that in an inclusion chain, the use of require_once() will assure that the code is added to your script only once, and avoid clashes with variable values or function names that can happen.

For example, if you create the following 2 include files `utils.php` and `foolib.php`

Example 11-3. utils.php
    <?php
    define("PHPVERSION", floor(phpversion()));
    echo "GLOBALS ARE NICE\n";
    function goodTea()
    {
        return "Oolong tea tastes good!";
    }
    ?>

Example 11-4. foolib.php
    <?php
    require ("utils.php");
    function showVar($var)
    {
        if (PHPVERSION == 4) {
            print_r($var);
        } else {
            var_dump($var);
        }
    }

    // bunch of other functions ...
    ?>

And then you write a script `cause_error_require.php`

Example 11-5. cause_error_require.php
    <?php
    require("foolib.php");
    /* the following will generate an error */
    require("utils.php");
    $foo = array("1",array("complex","quaternion"));
    echo "this is requiring utils.php again which is also\n";
    echo "required in foolib.php\n";
    echo "Running goodTea: ".goodTea()."\n";
    echo "Printing foo: \n";
    showVar($foo);
    ?>

When you try running the latter one, the resulting ouptut will be (using PHP 4.01pl2):

    GLOBALS ARE NICE
    GLOBALS ARE NICE

    Fatal error:  Cannot redeclare goodTea() in utils.php on line 5

By modifying `foolib.php` and `cause_errror_require.php` to use require_once() instead of require() and renaming the last one to `avoid_error_require_once.php`, we have:

Example 11-6. foolib.php (fixed)
    ...
    require_once("utils.php");
    function showVar($var)
    {
    ...

Example 11-7. avoid_error_require_once.php
    ...
    require_once("foolib.php");
    require_once("utils.php");
    $foo = array("1",array("complex","quaternion"));
    ...

And when running the latter, the output will be (using PHP 4.0.1pl2):

    GLOBALS ARE NICE
    this is requiring globals.php again which is also
    required in foolib.php
    Running goodTea: Oolong tea tastes good!
    Printing foo:
    Array
    (
        [0] => 1
        [1] => Array
            (
                [0] => complex
                [1] => quaternion
            )

    )

Also note that, analogous to the behavior of the `#include` of the C preprocessor, this statement acts at "compile time", e.g. when the script is parsed and before it is executed, and should not be used for parts of the script that need to be inserted dynamically during its execution. You should use include_once() or include() for that purpose.

For more examples on using require_once() and include_once(), look at the PEAR code included in the latest PHP source code distributions.

See also: require(), include(), include_once(), get_required_files(), get_included_files(), readfile(), and virtual().

Prev | Home | Next
include() | Up | include_once()