[#1] powtac at gmx dot de [2015-09-02 13:36:55]

"require_once" and "require" are language constructs and not functions. Therefore they should be written without "()" brackets!

[#2] inci szlk [2015-05-22 16:32:42]

you can also use this type define to get exact path of root directory. So, it won't mess if the file is in whatever directory in whatever directory.

if (!defined("DOCUMENT_ROOT")) define("DOCUMENT_ROOT", $_SERVER['DOCUMENT_ROOT']);

require_once DOCUMENT_ROOT.'/hello/world.php';

[#3] Dodo [2014-06-28 22:41:03]

If you happen to encounter some "Warning: require_once(): failed to open stream" and you are certain the provided path is right, consider the following example & solution.

Considering the following tree:
+ C:\server\absolute\path\
+ somefolder\
- index.php
+ supbath
+ anotherfolder1\
- file1.php
- file2.php
+ anotherfolder2\
- file3.php

With the respective sources:
original index.php:
<?php

    // absolute path
    // inclusion status: SUCCESS
    require_once 'C:\server\absolute\path\subpath\anotherfolder1\file1.php';

?>

original file1.php:
<?php

    // relative path
    // inclusion status: SUCCESS
    require_once 'file2.php';

    // relative path
    // inclusion status: FAILURE
    require_once '../anotherfolder2/file3.php';

?>

You will notice the use of "\" as DIRECTORY_SEPARATOR, but the same result is obtained using "/".
Assumption ? PHP does not behave as it should if it encounters a relative path starting by a '../'. Well, this is not true.

Below is a modified file1.php:
<?php

    // absolute path
    // inclusion status: SUCCESS
    require_once '/file2.php';

    // absolute path
    // inclusion status: SUCCESS
    require_once '/../anotherfolder2/file3.php';

?>

It seems that PHP recognizes a non-prefixed file name as an absolute path in a require_once, and that it computes this absolute path from a relative context.

I am not sure this is the expected behaviour, but it was quite hard to figure out. Also, if you want to recognize those special cases where you had to specify a relative path starting with a "/", you can use the following trick.

<?php

    // it goes down one level, and then goes up one level : the result is neutral, but after prefixing your paths with this, PHP handles them
    define ('REQUIRE_TRICK', '/TRICK/../');

    require_once REQUIRE_TRICK . 'file2.php';
    require_once REQUIRE_TRICK . '../anotherfolder2/file3.php';

?>

If this ever gets reworked/fixed, it will be easy to remove the define.

[#4] acholoc at gmail dot com [2014-01-04 21:43:02]

I think it's important (at least for beginners) to mention somewhere clearly visible that require_once, when being used in a class, cannot be outside a function. (I am aware that even this, i.e. using it within the function is bad practice). However, that information could have saved me some valuable time troubleshooting the "unexpected T_REQUIRE_ONCE" error.

[#5] sudanisayfree at gmail dot com [2013-10-04 06:53:53]

1 requests  ?  338?B transferred  ?  600?ms (load: 655?ms, DOMContentLoaded: 657?ms)
gtes.cwahi.net
600?ms0?ms
HeadersPreviewResponseCookiesTiming
Request URL:http://gtes.cwahi.net/
Request Method:GET
Status Code:200 OK
Request Headersview source
Accept:text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*
 
 //require ('/www/includes/example.com/code/conf/sql_servers.inc');
 //require ('../../includes/example.com/code/conf/sql_servers.inc');
 //require_once ('/www/includes/example.com/code/conf/sql_servers.inc');
 //require_once ('../../includes/example.com/code/conf/sql_servers.inc');
 
 $end_time = microtime(true);
 
 $handle = fopen("/tmp/results", "ab+");
 fwrite($handle, ($end_time - $start_time) . "\n");
 fclose($handle);
?>

The test:
  I ran ab on the test.php script with a different require*() uncommented each time:
  ab -n 1000 -c 10 www.example.com/test.php

RESULTS:
--------
The average time it took to run test.php once:
require('absolute_path'):      0.000830569960420
require('relative_path'):      0.000829198306664
require_once('absolute_path'): 0.000832904849136
require_once('relative_path'): 0.000824960252097

The average was computed by eliminating the 100 slowest and 100 fastest times, so a total of 800 (1000 - 200) times were used to compute the average time.  This was done to eliminate any unusual spikes or dips.

The question of how many stat() system calls were made can be answered as follows:
- If you run httpd -X and then do an strace -p <pid_of_httpd>, you can view the system calls that take place to process the request.
- The most important thing to note is if you run test.php continuously (as the ab test does above), the stat() calls only happen for the first request:

  first call to test.php (above):
  -------------------------------
  lstat64 ("/www", {st_mode=S_IFDIR|0755, st_size=...
  lstat64 ("/www/includes", {st_mode=S_IFDIR|0755,...
  lstat64 ("/www/includes/example.com", {st_mode=S...
  lstat64 ("/www/includes/example.com/code", {st_m...
  lstat64 ("/www/includes/example.com/code/conf", ...
  lstat64 ("/www/includes/example.com/code/conf/sql_servers.inc", {st_mode...
  open ("/www/includes/example.com/code/conf/sql_servers.inc", O_RDONLY) = 17
  
  subsequent calls to test.php:
  -----------------------------
  open ("/www/includes/example.com/code/conf/sql_servers.inc", O_RDONLY) = 17

- The lack of stat() system calls in the subsequent calls to test.php only happens when test.php is called continusly.  If you wait a certain period of time (about 1 minute or so), the stat() calls will happen again.
- This indicates that either the OS (Ubuntu Linux in my case), or Apache is "caching" or knows the results of the previous stat() calls, so it doesn't bother repeating them.
- When using absolute_path there are fewer stat() system calls.
- When using relative_path there are more stat() system calls because it has to start stat()ing from the current directory back up to / and then to the include/ directory.

CONCLUSIONS:
------------
- Try to use absolute_path when calling require*().
- The time difference between require_once() vs. require() is so tiny, it's almost always insignificant in terms of performance.  The one exception is if you have a very large application that has hundreds of require*() calls.
- When using APC opcode caching, the speed difference between the two is completely irrelevant.
- Use an opcode cache, like APC!

Konstantin Rozinov
krozinov [at] gmail

[#12] cnorthcote at underground dot co dot uk [2008-03-14 03:20:57]

Bear in mind that require_once doesn't have a return value (neither does require; since they both halt execution on failure), so this won't work:

<?php

require_once("path/to/myfile.php") or die("Couldn't load myfile");

?>

because you will get a very unhelpful error:

PHP Fatal error:  require_once() : Failed opening required '1' (include_path='.;C:\\php5\\pear') in C:\path\to\code.php on line 1

This was mentioned on the php-general mailing list in about 2003 but is a gotcha I have seen a few people come across. If you want to check to see if a file was included, use @include() instead.

[#13] amcewen at look dot ca [2008-02-11 07:00:10]

Perhaps it would be clearer to say that require_once() includes AND evaluates the resulting code once.  More specifically, if there is code in the script file other than function declarations, this code will only be executed once via require_once().

[#14] manuel schaffner [2007-06-14 14:02:16]

The path for nested require_once() is always evaluated relative to the called / first file containing require_once(). To make it more flexible, maintain the include_path (php.ini) or use set_include_path() - then the file will be looked up in all these locations.

[#15] jazfresh at hotmail.com [2007-03-07 23:22:43]

Check how many files you are including with get_required_files(). If it's a significant number (> 100), it may be worth "compiling" the main PHP file. By "compiling", I mean write a script that reads a PHP file and replaces any "include/require_once" references with either:
- the file that it's requiring
- a blank line if that file has been included before

This function can be recursive, thus building up a large PHP file with no require_once references at all. The speedup can be dramatic. On one of our pages that included 115 classes, the page was sped up by 60%.

[#16] sneskid at hotmail dot com [2007-01-19 12:00:45]

<?php
function & rel($r, &$f) {return file_exists( ( $f = ( dirname($r).'/'.$f ) ) );}
function & relf($r, $f) {return rel($r,$f) ? file_get_contents($f) : null;}
function & reli($r, $f) {return rel($r,$f) ? include($f) : null;}
function & relr($r, $f) {return rel($r,$f) ? require($f) : null;}
function & relio($r, $f) {return rel($r,$f) ? include_once($f) : null;}
function & relro($r, $f) {return rel($r,$f) ? require_once($f) : null;}
?>

I found it useful to have a function that can load a file relative to the calling script and return null if the file did not exist, without raising errors.

<?php

echo relf(__FILE__, 'some.file');
?>

It was easy to modify and just as useful for require/include.

<?php

relro(__FILE__, 'stats.php');
?>

If you work with a deep php file structure and a barrage of includes/requires/file-loads this works well.

[#17] rejjn at mail dot nu [2006-09-01 02:28:58]

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.

[#18] antoine dot pouch at mcgill dot ca [2006-03-10 07:13:45]

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.

[#19] martijn(dot)lowrider(at)gmail(dot)com [2006-02-24 11:00:58]

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();
}

----------------------------------------------------------------------

[#20] miqrogroove [2005-05-01 11:10:02]

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

[#21] ulderico at maber dot com dot br [2005-03-22 05:38:04]

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.

[#22] Pure-PHP [2005-03-17 14:19:07]

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")

[#23] jtaal at eljakim dot nl [2005-03-10 05:00:35]

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
// http://www.apieye.com/528.html
function getfiles( $path , &$files = array() ) {
    if ( !is_dir( $path ) ) return null;
    $handle = opendir( $path );
    while ( false !== ( $file = readdir( $handle ) ) ) {
        if ( $file != '.' && $file != '..' ) {
            $path2 = $path . '/' . $file;
            if ( is_dir( $path2 ) ) {
                getfiles( $path2 , $files );
            } else {
                if ( preg_match( "/\.(php|php5)$/i" , $file ) ) {
                    $files[] = $path2;
                }
            }
        }
    }
    return $files;
}
$files = getfiles('/png/www/example.com/public_html/app/wordpress');
$br = (php_sapi_name() == "cli") ? "\n" : "<br />";
foreach($files as $file){
  opcache_compile_file($file);
  echo $file.$br; 
}