PHP require_once 语句

最后修改于 2025 年 4 月 16 日

PHP 的 require_once 语句用于在脚本执行期间包含并评估指定的文件。它防止多次包含同一文件。这对于模块化 PHP 编程至关重要。

基本定义

require_once 仅包含并评估文件一次。如果之前包含过该文件，则不会再次包含它。这可以防止函数重定义和变量重新赋值。

与 include 不同，如果找不到文件，require_once 会产生一个致命错误。它适用于对应用程序功能至关重要的文件。该语句与 require 相同，除了 once 行为之外。

语法：require_once 'filename.php';。路径可以是绝对路径或相对路径。如果给定相对路径，PHP 会搜索 include_path。

基本 require_once 用法

此示例演示了如何使用 require_once 包含配置文件。

config.php

<?php

// Database configuration
define('DB_HOST', 'localhost');
define('DB_USER', 'root');
define('DB_PASS', 'secret');
define('DB_NAME', 'testdb');

index.php

<?php

require_once 'config.php';

echo "Database host: " . DB_HOST;

代码包含 config.php，它定义了数据库常量。这些常量在 index.php 中可用。使用 require_once 可确保 config 仅加载一次。这是一种常见的配置文件模式。

包含类定义

此示例演示了如何使用 require_once 包含类定义文件。

User.php

<?php

class User {
    private $name;
    
    public function __construct($name) {
        $this->name = $name;
    }
    
    public function getName() {
        return $this->name;
    }
}

app.php

<?php

require_once 'User.php';

$user = new User('John Doe');
echo $user->getName();

User 类在 User.php 中定义，并在 app.php 中包含。这种分离遵循单一责任原则。 require_once 可防止多次类定义。这对于面向对象的 PHP 至关重要。

防止多次包含

此示例演示了 require_once 如何防止重复包含。

functions.php

<?php

function greet() {
    return "Hello!";
}

main.php

<?php

require_once 'functions.php';
require_once 'functions.php'; // Won't include again

echo greet();

functions.php 文件包含一个简单的函数。 Main.php 使用 require_once 包含它两次。第二次包含被跳过。如果没有 require_once，这将导致函数重定义的致命错误。

相对路径与绝对路径

此示例比较了在 require_once 中使用相对路径和绝对路径。

project/index.php

<?php

// Relative path
require_once '../lib/utils.php';

// Absolute path
require_once __DIR__ . '/../lib/utils.php';

两种方法都从 lib 目录中包含 utils.php。相对路径取决于当前工作目录。使用 __DIR__ 的绝对路径更可靠。这可以防止文件移动时出现问题。

条件文件包含

此示例显示了如何使用 require_once 有条件地包含文件。

feature.php

<?php

if (ENABLE_FEATURE) {
    require_once 'advanced_feature.php';
    // Use advanced functionality
} else {
    require_once 'basic_feature.php';
    // Use basic functionality
}

代码在包含文件之前检查一个常量。这允许功能切换。每个分支都使用 require_once 来处理其特定的实现文件。这种模式对于插件系统很有用。文件仅在需要时加载。

自动加载类

此示例演示了如何在简单的自动加载器中使用 require_once。

autoload.php

<?php

spl_autoload_register(function ($class) {
    require_once 'classes/' . $class . '.php';
});

$obj = new MyClass();

自动加载器在需要时自动包含类文件。每个类文件仅被 require 一次。这消除了手动 require_once 语句。该模式遵循 PSR-4 自动加载标准。

错误处理

此示例显示了如何优雅地处理 require_once 失败。

error_handling.php

<?php

try {
    require_once 'missing_file.php';
} catch (Throwable $e) {
    error_log("Failed to load file: " . $e->getMessage());
    require_once 'fallback.php';
}

代码尝试包含一个不存在的文件。错误被捕获并记录。而是包含一个备用文件。这使应用程序更加健壮。始终在生产代码中处理 require_once 失败。

最佳实践

重要文件： 对关键依赖项使用 require_once。
绝对路径： 偏好使用 __DIR__ 来获得可靠的文件位置。
自动加载： 实现自动加载器以实现类文件。
错误处理： 捕获并处理包含错误。
性能： 尽量减少文件包含以提高性能。

来源

PHP require_once 文档

本教程涵盖了 PHP require_once，并提供了实用示例，展示了各种场景中的文件包含模式和最佳实践。

作者

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

列出所有 PHP 教程。