Including Code (Programming PHP)

2.6. Including Code

PHP provides two constructs to load code and HTML from another module: require and include. They both load a file as the PHP script runs, work in conditionals and loops, and complain if the file being loaded can't be found. The main difference is that attempting to require a nonexistent file is a fatal error, while attempting to include such a file produces a warning but does not stop script execution.

A common use of include is to separate page-specific content from general site design. Common elements such as headers and footers go in separate HTML files, and each page then looks like:

<? include 'header.html'; ?>
content
<? include 'footer.html'; ?>

We use include because it allows PHP to continue to process the page even if there's an error in the site design file(s). The require construct is less forgiving and is more suited to loading code libraries, where the page can't be displayed if the libraries don't load. For example:

require 'codelib.inc';
mysub( );               // defined in codelib.inc

A marginally more efficient way to handle headers and footers is to load a single file and then call functions to generate the standardized site elements:

<? require 'design.inc';
   header( );
?>
content
<? footer( ); ?>

If PHP cannot parse some part of a file included by include or require, a warning is printed and execution continues. You can silence the warning by prepending the call with the silence operator; for example, @include.

If the allow_url_fopen option is enabled through PHP's configuration file, php.ini, you can include files from a remote site by providing a URL instead of a simple local path:

include 'http://www.example.com/codelib.inc';

If the filename begins with "http://" or "ftp://", the file is retrieved from a remote site and then loaded.

Files included with include and require can be arbitrarily named. Common extensions are .php, .inc, and .html. Note that remotelyfetching a file that ends in .php from a web server that has PHP enabled fetches the output of that PHP script. For this reason, we recommend you use .inc for library files that primarily contain code and .html for library files that primarily contain HTML.

If a program uses include or require to include the same file twice, the file is loaded and the code is run or the HTML is printed twice. This can result in errors about the redefinition of functions or multiple copies of headers or HTML being sent. To prevent these errors from occurring, use the include_once and require_once constructs. They behave the same as include and require the first time a file is loaded, but quietly ignore subsequent attempts to load the same file. For example, many page elements, each stored in separate files, need to know the current user's preferences. The element libraries should load the user preferences library with require_once. The page designer can then include a page element without worrying about whether the user preference code has already been loaded.

Code in an included file is imported at the scope that is in effect where the include statement is found, so the included code can see and alter your code's variables. This can be useful—for instance, a user-tracking library might store the current user's name in the global $user variable:

// main page
include 'userprefs.inc';
echo "Hello, $user.";

The ability of libraries to see and change your variables can also be a problem. You have to know every global variable used by a library to ensure that you don't accidentally try to use one of them for your own purposes, thereby overwriting the library's value and disrupting how it works.

If the include or require construct is in a function, the variables in the included file become function-scope variables for that function.

Because include and require are keywords, not real statements, you must always enclose them in curly braces in conditional and loop statements:

for ($i=0; $i < 10; $i++) {
  include "repeated_element.html";
}

Use the get_included_files( ) function to learn which files your script has included or required. It returns an array containing the full system path filenames of each included or required file. Files that did not parse are not included in this array.