PHP include_once Statement

The include_once statement in PHP includes and evaluates a specified file only once during script execution. Unlike the regular include statement, include_once prevents the same file from being loaded multiple times, which helps avoid redefinition errors and improves performance.

The include_once statement is commonly used for loading configuration files, libraries, or setting up global variables that should only be initialized once during application execution.

Syntax

include_once 'filename.php';
// or
include_once('filename.php');

Basic Example

Here's a simple demonstration of how include_once works ?

<?php
echo "Main script started
";

// This will include the code below
include_once 'test_content.php';

echo "Main script ended
";

// Simulating test_content.php
function simulateIncludedFile() {
    echo "This content is included once
";
}
simulateIncludedFile();
?>

Main script started
This content is included once
Main script ended

Preventing Multiple Inclusions

The key advantage of include_once is preventing duplicate inclusions. Here's an example showing this behavior ?

<?php
echo "First include_once call:
";
include_once 'config_simulation.php';

echo "Second include_once call:
";
include_once 'config_simulation.php';

echo "Script completed
";

// Simulating config_simulation.php
function simulateConfig() {
    static $called = false;
    if (!$called) {
        echo "Configuration loaded
";
        $called = true;
    }
}
simulateConfig();
?>

First include_once call:
Configuration loaded
Second include_once call:
Script completed

Error Handling

When a file cannot be found, include_once generates a warning but continues script execution ?

<?php
echo "Before include_once
";

// This will generate a warning
@include_once "nonexistent_file.php";

echo "After include_once - script continues
";
?>

Before include_once
After include_once - script continues

Return Values

The include_once statement returns different values based on the situation ?

<?php
// First call - returns the included file's return value
$result1 = include_once 'return_simulation.php';
echo "First call result: " . var_export($result1, true) . "
";

// Second call - returns TRUE (already included)
$result2 = include_once 'return_simulation.php';
echo "Second call result: " . var_export($result2, true) . "
";

// Simulating return_simulation.php
function simulateReturn() {
    static $called = false;
    if (!$called) {
        $called = true;
        return "Hello from included file";
    }
    return true;
}

// Only call on first execution
if (!function_exists('alreadyDefined')) {
    function alreadyDefined() {}
    return simulateReturn();
}
?>

First call result: 'Hello from included file'
Second call result: true

Comparison with Other Include Statements

Conclusion

Use include_once when you need to ensure a file is loaded only once during execution, particularly for configuration files and library inclusions. It provides safety against redefinition errors while allowing script execution to continue if the file is not found.