require_once()

require_once() 语句在脚本执行期间包含并运行指定文件。此行为和 require() 语句类似,唯一区别是如果该文件中的代码已经被包含了,则不会再次包含。有关此语句怎样工作参见 require() 的文档。

require_once() 应该用于在脚本执行期间同一个文件有可能被包含超过一次的情况下,想确保它只被包含一次以避免函数重定义,变量重新赋值等问题。

使用 require_once()include_once() 的例子见最新的 PHP 源程序发行包中的 PEAR 代码。

返回值和 include() 相同。如果文件已被包含,本函数返回 TRUE

注: require_once() 是 PHP 4.0.1pl2 中新加入的。

注: 要注意 require_once()include_once() 在大小写不敏感的操作系统中(例如 Windows)的行为可能不是所期望的。

例子 16-12. require_once() 在 Windows 下不区分大小写

<?php
require_once("a.php"); // this will include a.php
require_once("A.php"); // this will include a.php again on Windows!
?>
此行为在 PHP 5 中改了,路径先被规格化,因此 C:\PROGRA~1\A.phpC:\Program Files\a.php 的实现一样,文件只会被包含一次。

警告

Windows 版本的 PHP 在 4.3.0 版之前不支持本函数的远程文件访问,即使 allow_url_fopen 选项已被激活。

参见 require()include()include_once()get_required_files()get_included_files()readfile()virtual()


add a note add a note User Contributed Notes
rejjn at mail dot nu
01-Sep-2006 05:28
The following only applies to case insensitive systems like Windows.

Even though the documentation sais that "the path is normalized" that doesn't seem to be true in all cases.

If you are using the magic __autoload() function (or if the framework you're using is using it) and it includes the requested class file with complete path or if you override the include path in mid execution, you may have some very strange behavior. The most subtle problem is that the *_once functions seem to differentiate between c:\.... and C:\....

So to avoid any strange problems and painfull debugging make sure ALL paths you use within the system have the same case everywhere, and that they correspond with the actual case of the filesystem. That includes include paths set in webserver config/php.ini, auto load config, runtime include path settings or anywhere else.
antoine dot pouch at mcgill dot ca
10-Mar-2006 11:13
require_once (and include_once for that matters) is slow.
Furthermore, if you plan on using unit tests and mock objects (i.e. including mock classes before the real ones are included in the class you want to test), it will not work as require() loads a file and not a class.

To bypass that, and gain speed, I use :

<?php
class_exists
('myClass') || require('path/to/myClass.class.php');
?>

I tried to time 100 require_once on the same file and it took the script 0.0026 seconds to run, whereas with my method it took only 0.00054 seconds. 4 times faster ! OK, my method of testing is quite empirical and YMMV but the bonus is the ability to use mock objects in your unit tests.
martijn(dot)lowrider(at)gmail(dot)com
25-Feb-2006 03:00
How to use Require_Once with error reporting to include a MySQL Connection file:

-------------------------------------------------------------------
$MySQLConnectFile = './inc/MySQL.Class.php';

if ( is_dir ( './inc/' ) )
{
   $IncIsDir == TRUE;
}

if ( file_exists ( $MySQLConnectFile ) )
{
   $MySQLFileExists == TRUE;
}

if ( $IncIsDir && $MySQLFileExists )
{
   require_once ( $MySQLConnectFile )
}
else
{
   echo '<b>Error:</b> <i>Could not read the MySQL Connection File. Please try again later.';
   exit();
}

----------------------------------------------------------------------
sdh00b at gmail dot com
05-Dec-2005 11:12
@georg_gruber at yahoo dot com

Files for including are first looked in include_path relative to the current working directory and then in include_path relative to the directory of current script. E.g. if your include_path is ., current working directory is /www/, you included include/a.php and there is include "b.php" in that file, b.php is first looked in /www/ and then in /www/include/. If filename begins with ./ or ../, it is looked only in include_path relative to the current working directory.

Taken from http://us2.php.net/manual/en/function.include.php
georg_gruber at yahoo dot com
07-Oct-2005 06:06
A very interesting behaviour of require_once (and probably all include commands):

consider the following files:

/index.php -> require_once('/inc/library.php');
/function1.php -> print('/function1.php');
/inc/library.php -> require_once('function1.php');
/inc/function1.php -> print('/inc/function1.php');

Note that /function1.php and /inc/function1.php are files with the SAME filename in different folders.

If you "/index.php" is executed it will output
"/function1.php".

Although /index.php "includes" /inc/library.php the scope of the file is still /index.php therefor /function1.php will be found even it could be asumed the /inc/function1.php is the correct one.

And it gets more interesting: if you delete /function1.php and execute /index.php PHP checks this and "includes" /inc/function1.php.
miqrogroove
02-May-2005 02:10
require_once() is NOT independent of require().  Therefore, the following code will work as expected:

echo.php
<?php
echo "Hello";
?>

test.php
<?php
require('echo.php');
require_once(
'echo.php');
?>

test.php outputs: "Hello".

Enjoy,
-- Miqro
ulderico at maber dot com dot br
22-Mar-2005 09:38
With both of your functions guys, Pure-PHP and jtaal at eljakim dot nl, you'll not have any variables available GLOBALly if they're supposed to be globals...

That's why my import handles better those situation. OK, SOME MAY DISPUTE that using include_once and require_once may slow down an application. But what's the use to do IN PHP what the interpreter *should* do better for you. Thusly these workarounds shall, some time in the future, DIE.

Thus It's better to well design your application to keep some order using few INCLUDES and REQUIRES in it rather than insert MANY AND SEVERAL *_once around.
Pure-PHP
18-Mar-2005 06:19
require_once can slower your app, if you include to many files.

You cann use this wrapper class, it is faster than include_once

http://www.pure-php.de/node/19

require_once("includeWrapper.class.php")

includeWrapper::require_once("Class1.class.php");
includeWrapper::require_once("Class1.class.php");
includeWrapper::require_once("Class2.class.php")
jtaal at eljakim dot nl
10-Mar-2005 09:00
When you feel the need for a require_once_wildcard function, here's the solution:

<?php // /var/www/app/system/include.inc.php

function require_once_wildcard($wildcard, $__FILE__) {
 
preg_match("/^(.+)\/[^\/]+$/", $__FILE__, $matches);
 
$ls = `ls $matches[1]/$wildcard`;
 
$ls = explode("\n", $ls);
 
array_pop($ls); // remove empty line ls always prints
 
foreach ($ls as $inc) {
   require_once(
$inc);
  }
}

?>

The $__FILE__ variable should be filled with the special PHP construct __FILE__:
<?php // /var/www/app/classes.inc.php

require_once('system/include.inc.php');
require_once_wildcard("classes/*.inc.php", __FILE__);

?>

The (*.inc.php) files inside the directory classes are automagically included using require_once_wildcard.

This solution may not be as useful when using PHP5 in combination with classes and the autoload feature.

--
Jaap Taal
thomas dot revell at uwe dot ac dot uk
21-Jan-2005 06:00
Regarding the case insensitivity problems on Windows, it looks to me as though it is a problem in PHP5 as well (at least in some cases).

The following gave me problems:

From file URLSwitcher.php
<?php
require_once 'slimError/slimError.php';
require_once
'Navigator_Cache.php';
....
?>

From file Navigator_Cache.php
<?php
require_once 'slimError/slimerror.php';
...
?>

From file slimerror.php
<?php
class SLIMError {
...
}
?>
The above setup gave me an error : "Cannot redeclare class SLIMError"

If I change the require_once in URLSwitcher.php to match the one in Navigator_Cache.php, there isn't a problem, but if I do this the other way round, the same problem occurs.
19-Mar-2004 01:49
> Mac OS X systems are also not case-sensitive.
That depends on the filesystem:
- HFS and HFS+ are NOT case sensitive.
- UFS is case sensitive.
jaisen - at - jmathai - dot - com
13-Mar-2004 04:16
NOTE: This function changed how it worked.  In PHP 3 this behaved very differently than it does on PHP 4.  Require used to include and parse the file regardless where the require line was positioned.

For example (PHP3):

<?php
 
if(false){ require_once 'file_does_not_exist.php'; }
?>

That code throw a fatal exception even though it's in a conditional block which evaluates to false.  In PHP 4 the file is never included or parsed, so no exception is thrown.

For example (PHP4)
<?php
 
if(false){ require_once '1_file_does_not_exists.php'; }
  require_once
'2_file_does_not_exists.php';
?>

Stops execution of the script on trying to require the 2nd file...by bypasses the first require.

--JM