Delicious Bookmark this on Delicious Share on Facebook SlashdotSlashdot It! Digg! Digg



PHP : Language Reference : Control Structures : require

require

The require() statement includes and evaluates the specific file.

require() includes and evaluates a specific file. Detailed information on how this inclusion works is described in the documentation for include().

require() and include() are identical in every way except how they handle failure. They both produce a Warning, but require() results in a Fatal Error. In other words, don't hesitate to use require() if you want a missing file to halt processing of the page. include() does not behave this way, the script will continue regardless. Be sure to have an appropriate include_path setting as well.

Example 7.4. Basic require() examples

copy to clipboard
<?php

require 'prepend.php';

require $somefile;

require ('somefile.txt');

?>


See the include() documentation for more examples.

Note:

Prior to PHP 4.0.2, the following applies: require() will always attempt to read the target file, even if the line it's on never executes. The conditional statement won't affect require(). However, if the line on which the require() occurs is not executed, neither will any of the code in the target file be executed. Similarly, looping structures do not affect the behaviour of require(). Although the code contained in the target file is still subject to the loop, the require() itself happens only once.

Note:

Because this is a language construct and not a function, it cannot be called using variable functions

Warning:

Windows versions of PHP prior to PHP 4.3.0 do not support accessing remote files via this function, even if allow_url_fopen is enabled.

See also include(), require_once(), include_once(), get_included_files(), eval(), file(), readfile(), virtual() and include_path.

Related Examples ( Source code ) » require

Examples ( Source code ) » Form value validation
Examples ( Source code ) » Form Data Validation With Error Count
Examples ( Source code ) » Declaring a Function That Requires Arguments
Examples ( Source code ) » Animated Talking Captcha php class
Examples ( Source code ) » Feed Validator
Examples ( Source code ) » E-mail address validation class
Examples ( Source code ) » XmlRpcServer extends HttpResponse
Examples ( Source code ) » XmlRpcClient using HttpRequest
Examples ( Source code ) » Insert, Update, Delete, Create and Drop OCI8
Examples ( Source code ) » Executing SQL Statements With OCI8 Transactions
Examples ( Source code ) » Create report in PDF format from Crystal Report via PHP and COM
Examples ( Source code ) » Posting a file / image to twitpic.com using PHP and cUrl

Code Examples / Notes » require

tjeerd
When using symbolic links with PHP, specify a dotslash './page.php' path to ensure that PHP is looking in the right directory with nested requires:
E.g. when the required actual page1.php contains other require statements to, say page2.php, PHP will search the path that the symbolic link points to, instead of the path where the symbolic link lives. To let PHP find the other page2.php in the path of the symbolic link, a require('./page2.php'); statement will solve the puzzle.

steve
WARNING: Be absolutely sure that your include paths are relative or directory based and not http!!!
  require("http://www.mydomain.com/somefile.php"); //WRONG!!
  require("usr/mydomain/somefile.php"); //CORRECT!!
If you are intending to access local files and you accidentally use an http address, the request will probably work. However, this creates a wierd situation that can cause all sorts of bugs in your scripts and slow your code down.
The problem is that the include spawns off another php request, and is essentially requesting the file in the same a way a remote viewer would. So rather than including the intended php code, instead you get the processed output from that single file executed in its own private scope.
It's a simple mistake, but it can be an awful problem to debug.
Walker

marc
This will sound elementary, but for C++ native programmers, be sure NOT to put a '#' in front of your include statements! The parser will not give you an error, but also will not include the file, making for a tedious debugging process.
In short, USE:
<?php
    include "yourfile.php";
?>
and DON'T use:
<?php
    #include "yourfile.php";
?>

tuxedobob
Something which may not be immediately obvious is that if you use double quotes on the filename, you can use variables to specify the filename, allowing you to do something like this:
<?php
$query = "SELECT filename FROM updates WHERE version>$current ORDER BY version";
$updateresult = mysql_query($query) or exit($query.'<br />'.mysql_error());
while ($updaterow = mysql_fetch_row($updateresult)) {
   require "$updaterow[0]";
}
?>
Drop this in a script on a server and you can push updates to your clients. Obviously, make sure you only run scripts you want to.

moazzamk
require and include read the included files even if they are not executed in the code. You can use eval() to avoid this.
eval('require filename;');
I don't know if it's faster to have the files included the regular way or the eval way though (in other words, I haven't tested their efficiency). It will be great if someone can test which is better.

chris
Remember, when using require that it is a statement, not a function. It's not necessary to write:
<?php
require('somefile.php');
?>
The following:
<?php
require 'somefile.php';
?>
Is preferred, it will prevent your peers from giving you a hard time and a trivial conversation about what require really is.

dave
re: danielm at unb dot br...
$_SERVER['DOCUMENT_ROOT'] is very useful, but it is not available with all web servers. Apache has it; IIS doesn't.
I use the following to make my PHP applications work in more situations:
<?php
if (!defined("BASE_PATH")) define('BASE_PATH', isset($_SERVER['DOCUMENT_ROOT']) ? $_SERVER['DOCUMENT_ROOT'] : substr($_SERVER['PATH_TRANSLATED'],0, -1*strlen($_SERVER['SCRIPT_NAME'])));
?>
...but even that gets tripped up by symlinks to different mount points, etc. You could substitute realpath($_SERVER['PATH_TRANSLATED']), but that function has been reported not to work on some (Windows) servers. One could use the PATH_TRANSLATED for both servers, but I figure if Apache is going to tell me exactly what I want to know, I should listen.

peter mcdonald
re the comment by moazzamk at gmail dot com
As the manual states require and require_once as of PHP 4.02 no longer call the file if the line of code it is on should not be executed.

10-feb-2005 06:29
Note when calling any require or include function, that the call will block if the script given as the parameter is excecuting.
Because of this one should be careful when using blocking functions like sleep() in a script which is included by another.

scott
If you want to verify that a file can be included or required, the simplest solution I've found is just to check that the file exists.
<?php
   if(file_exists($pageContentInc)){
       require_once $pageContentInc;
   }else{
       $pageContentInc = "common/content_404.inc";
       require_once $pageContentInc;
   }
?>
Does it really need to be any harder than that?

danielm
if you want to include files with an absolut path reference, you can use:
require ($_SERVER["DOCUMENT_ROOT"]."/path/to/file.php");
this way you can organize your files in subdirectories trees.

richardbrenner -at- gmx - at
If you use relativ paths in a php script (file A) that can be required by another php script (file B), be aware that the relativ paths in file A will be relativ to the directory, where file B is stored.
You can use the following syntax in file A, to be sure that the paths are relativ to the directory of file A:
<?
require(dirname(__FILE__)."/path/relative/file_to_include.php");
?>
Greetings,
Richard

gabe
If you are experiencing a bug related to using relative paths with include or require, it may be related to a grandparent directory that is executable but not readable.  It will cause __FILE__ to return a relative path instead of the full path which it is supposed to show.  This manifests itself in interesting ways that can be seemingly unrelated.  For instance, I discovered it using the Smarty {debug} command which failed to find its template due to this issue.  Please see the following for more details:
http://bugs.php.net/bug.php?id=34552
http://shiftmanager.net/~kurt/test/

daniel
I love php.  But when file can't be included, 'require' or 'require_once' throw fatal error and halt the script, which is almost never desirable on a mission-critical production server.  I think it may be better to use something like the following.  
<?php
if (@include 'plan_A.php') {
// Plan A;
} elseif (@include 'plan_B.php') {
   // Plan B;
} else {
   // Hope never happens.  If does, then Email the webmaster;
   // Call 911, Medic, Fire, Police, the president;
   // Change hard drive, server, hosting service;
}
?>
Or handle trouble first is you wish
<?php
if (!@include 'plan_A.php') {
// Someone has kidnapped/corrupted Plan_A.php;
// Email the webmaster;
// Change hard drive, server, hosting service;
} else {
   // Plan A;
}
?>

webmaster
I have learnt to manipulate this code into an effecitve and easy to use form. I use it with require_once, but it could be used for require.
require_once($_SERVER['DOCUMENT_ROOT'].'/includes/top.php');
This mainly jumps back to the servers document root and then begins to enter the directories defined until it finds the file. In this case it would go back to the root of the server, or whatever your document root is, and then enter includes. there it would search for the top.php file. Simple to use, yet effective...espcially for people like me who re-use code or move files to different directories. I don't have to fix the includes, because they all work the same way.

inc
I have found a problem when I try to access a php file via require($class_directory)
// # $class_directory contain a long full path and dot into the last folder.
// # $class_directory = "/var/.../app/system/plugintoto_1.0/class_plugintoto_1.0.php";
// dot ('.') and minus ('-') are not accepted in require !

some dot user
Discovered a bit of weird behavior yesterday involving require() (using PHP 5.2.3).  If you use require() inside a function, the "globals" in the file will be local to the function.  An example of this:
test.php:
<?php
 function TestFunc()
 {
   require('test2.php');
   echo "<pre>" . print_r($GLOBALS, true) . "</pre>";
 }
?>
test2.php:
<?php
 $MyTestGlobal = Array();
?>
This happens because require is a statement that _inlines_ the target code - not a function that gets called.
To fix this, use the $GLOBALS superglobal:
test2.php:
<?php
 $GLOBALS["MyTestGlobal"] = Array();
?>

31-jan-2007 11:38
A note that drove me nuts for 2 days!
Be carfull if you have a newline or blank space befor your php tags in the included/required file it will read as html and outputed.
If your running your output through javascript string evaluations which would be sensitive to newlines/white spaces be carfull that the first chars in the file are the php tages eg <?php

bmessenger
// Looks like I might have a fix for some on the
// relative path issue.
if (!function_exists('bugFixRequirePath'))
{
function bugFixRequirePath($newPath)
{
$stringPath = dirname(__FILE__);
if (strstr($stringPath,":")) $stringExplode = "\\";
else $stringExplode = "/";

$paths = explode($stringExplode,$stringPath);

$newPaths = explode("/",$newPath);

if (count($newPaths) > 0)
{
for($i=0;$i<count($newPaths);$i++)
{
if ($newPaths[$i] == "..") array_pop($paths);
}

for($i=0;$i<count($newPaths);$i++)
{
if ($newPaths[$i] == "..") unset($newPaths[$i]);
}

reset($newPaths);

$stringNewPath = implode($stringExplode,$paths).
$stringExplode.implode($stringExplode,$newPaths);

return $stringNewPath;
}
}
}
require_once(bugFixRequirePath("../config.php"));

Change Language


Follow Navioo On Twitter
if
else
elseif
Alternative syntax for control structures
while
do-while
for
foreach
break
continue
switch
declare
return
require
include
require_once
include_once
Terms of Service Privacy Policy Sitemap

©2024 -EPSILONSYS SOFTWARE inc

Other EPSILONSYS SOFTWARE Web Sites : Programming Resources | News Headline | Free local classifieds

eXTReMe Tracker