ZetCode

PHP include_once 语句

最后修改于 2025 年 4 月 16 日

PHP 的 include_once 语句在脚本执行期间包含并评估指定的文件。它防止多次包含同一个文件。这对于包含文件（如标头、页脚或配置）很有用。

基本定义

include_once 语句仅包含一次文件，即使被多次调用也是如此。如果找不到该文件，它会发出警告，但会继续执行。

与 include 不同，include_once 会检查文件是否已被包含。这可以防止函数重定义和变量值覆盖。

语法：include_once 'filename.php';。文件路径可以是绝对路径或相对路径。如果给出了相对路径，PHP 会搜索包含路径。

基本 include_once 用法

此示例演示了使用 include_once 包含配置文件。

config.php 
<?php
// Database configuration
define('DB_HOST', 'localhost');
define('DB_USER', 'root');
define('DB_PASS', 'secret');
define('DB_NAME', 'mydb');
index.php 
<?php

include_once 'config.php';

echo "Database host: " . DB_HOST;

该代码包含 config.php 一次，并使用其常量。如果多次包含，它不会重新定义常量。这可以防止“已定义”错误。该路径相对于当前脚本。

包含函数

此示例展示了如何包含包含函数定义的文件。

functions.php 
<?php

function calculateTotal(float $price, int $quantity): float
{
    return $price * $quantity;
}
order.php 
<?php

include_once 'functions.php';

$total = calculateTotal(12.99, 3);
echo "Order total: $" . $total;

该代码包含 functions.php 以访问其函数。使用 include_once 可以防止函数重定义错误。该函数在包含脚本的范围内可用。

包含 HTML 模板

此示例演示了包含 HTML 标头和页脚文件。

header.php 
<!DOCTYPE html>
<html>
<head>
    <title>My Website</title>
</head>
<body>
    <header>
        <h1>Welcome to My Site</h1>
    </header>
footer.php 
    <footer>
        <p>© 2025 My Website</p>
    </footer>
</body>
</html>
page.php 
<?php

include_once 'header.php';
?>
    <main>
        <p>This is the main content of the page.</p>
    </main>
<?php
include_once 'footer.php';

该代码通过包含标头和页脚来构建一个完整的 HTML 页面。使用 include_once 确保这些文件只包含一次。这种模式在基于模板的 PHP 应用程序中很常见。

防止多次包含

此示例展示了 include_once 如何防止多次包含同一个文件。

counter.php 
<?php

$counter = 0;
test.php 
<?php

include_once 'counter.php';
$counter++;
include_once 'counter.php'; // Won't execute again
$counter++;

echo "Counter value: " . $counter; // Outputs 2

该代码演示了 counter.php 仅被包含一次。第二个 include_once 被忽略。如果没有 include_once，$counter 将重置为 0。此行为可以防止变量重新初始化。

条件包含

此示例展示了在条件语句中使用 include_once。

admin_functions.php 
<?php

function adminDashboard()
{
    echo "Admin dashboard loaded.";
}
user.php 
<?php

$isAdmin = true;

if ($isAdmin) {
    include_once 'admin_functions.php';
    adminDashboard();
} else {
    echo "Regular user view.";
}

该代码仅为管理员用户有条件地包含管理员函数。如果需要，include_once 确保该文件只被包含一次。此模式对于基于角色的功能很有用。

从不同目录包含

此示例演示了从不同目录级别包含文件。

/lib/database.php 
<?php

function dbConnect()
{
    echo "Database connected.";
}
/public/index.php 
<?php

include_once __DIR__ . '/../lib/database.php';

dbConnect();

该代码使用 __DIR__ 创建包含文件的绝对路径。这确保无论工作目录如何都能找到该文件。路径解析在较大的应用程序中很重要。

使用 include_once 进行错误处理

此示例展示了如何使用 include_once 处理缺失文件。

missing_file.php 
<?php

if (@include_once 'nonexistent.php') {
    echo "File included successfully.";
} else {
    echo "File not found, using fallback.";
    // Fallback code here
}

该代码使用 @ 运算符来抑制警告。它检查 include_once 的返回值，以便优雅地处理失败。这种方法比让 PHP 发出警告更好。

最佳实践

来源

PHP include_once 文档

本教程涵盖了 PHP include_once，并提供了实际示例，展示了 PHP 应用程序中的文件包含模式、路径处理和错误管理。

作者

我叫 Jan Bodnar，是一位充满激情的程序员，拥有丰富的编程经验。自 2007 年以来，我一直在撰写编程文章。迄今为止，我撰写了 1,400 多篇文章和 8 本电子书。我拥有超过十年的编程教学经验。

列出 所有 PHP 教程。