Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Language Constructs and Statements

PHP include and require

Reference for PHP include, include_once, require and require_once: load other files, return values, path resolution and how failures differ.

include and require read another PHP file and run it at the point where the statement appears. They are how you split a program into several files: shared functions, configuration, class definitions and templates.

The two differ only in how they fail. If the file cannot be loaded, require stops the script with a fatal error, while include raises a warning and the script goes on. The _once variants skip the file if it has already been loaded, which prevents "cannot redeclare" errors.

PHP
require __DIR__ . '/vendor/autoload.php';
$config = include 'config.php';   // the file can `return` a value

Try it

PHP Loading a file that returns an array

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP include versus require when the file is missing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

A failed require cannot be demonstrated in a script that has to keep running, because it stops the program:

PHP
require '/no/such/file.php';
// Fatal error: Uncaught Error is NOT thrown; PHP reports "Failed opening required" (E_COMPILE_ERROR)
echo "never printed";

Syntax

PHP
include expression;
include_once expression;
require expression;
require_once expression;
Name Description
expression A string with the path of the file. Parentheses are allowed but not needed.

Return value: whatever the file returns with return; 1 if the file ran and returned nothing; false when include or include_once fails. include_once and require_once return true if the file was already loaded.

Errors: a missing file gives an E_WARNING with include and a fatal E_COMPILE_ERROR with require (it is not a catchable exception, and the script ends). A parse error in the loaded file throws ParseError.

Usage notes

  • Same scope. The loaded file shares the variable scope of the line that included it. Inside a function, it sees that function's local variables. A return at the top level of the file ends only that file.
  • Path resolution. A path starting with / or a drive letter is absolute. ./ and ../ are relative to the current working directory. Anything else is searched in include_path first, then in the calling script's directory. Build paths from __DIR__ to avoid surprises.
  • Use require for essentials. A missing class file or configuration should stop the program. Use include for optional parts, such as an optional template.
  • _once costs a lookup. It resolves the real path to compare with loaded files. For classes, an autoloader (see Autoloading) is better than many require_once lines.
  • Never include user input. include $_GET['page'] allows local and sometimes remote file inclusion attacks. Map allowed names to fixed files instead.
  • Leading output. Text outside <?php ... ?> tags in the included file is sent to the output, so stray whitespace before <?php shows up. This is why many files omit the closing tag.
  • Templates. Including a file that mixes HTML and PHP is the oldest templating method; see PHP tags and embedding.
  • Remote files. Including URLs needs allow_url_include, which is off by default and should stay off.