include_once

The PHP include_once Statement

include_once includes and evaluates a file during execution, but only if that file has not already been included in the current request. If the same file is requested again with include_once, PHP skips it silently. This makes it the safe choice for files that define functions, classes, or constants — including such a file twice would otherwise trigger a fatal "cannot redeclare" error.

This page covers the syntax, how include_once differs from include and require_once, what it returns, and the common cases where you actually reach for it.

Syntax

include_once is a language construct, so the parentheses are optional:

include_once 'filename.php';
include_once('filename.php'); // also valid

PHP tracks the file by its resolved real path. So include_once 'lib.php' and include_once './lib.php' that point at the same file on disk are treated as the same inclusion — the second one is skipped.

How include_once decides whether to include

The rule is one-included-per-request. The example below uses tempnam() to create a real file at runtime, write a function definition into it, then include it twice. Including a function definition twice with plain include would crash; include_once does not.

<?php

// Create a real file that defines a function.
$libFile = tempnam(sys_get_temp_dir(), 'lib');
file_put_contents($libFile, '<?php function greet($name) { return "Hello, $name!"; }');

include_once $libFile; // file is loaded, function defined
echo greet('Ada'), "\n";

include_once $libFile; // already included -> skipped, no redeclare error
echo greet('Linus'), "\n";

unlink($libFile);

// Output:
// Hello, Ada!
// Hello, Linus!

The second include_once does nothing because the file was already pulled in, so greet() is never redeclared.

Return value

include_once returns 1 on a fresh inclusion (when the file has no explicit return), and true if the file was already included. If the file cannot be found, it emits a warning and returns false (it does not stop the script — that is what require_once is for).

<?php

$result = include_once 'this-file-does-not-exist.php';
var_dump($result); // bool(false), plus a warning

// Output:
// bool(false)

A file can also return a value, which is handy for config files:

<?php

// config.php would contain: <?php return ['debug' => true];
$config = include_once 'config.php';

include_once vs the other three

PHP has four file-inclusion constructs. They differ on two axes — once or every time and warning or fatal error when the file is missing:

Use include_once when the file is optional but must not be loaded twice. Use require_once when the file is essential (a class your code can't run without) and must not be loaded twice.

When to use it

• Function and class libraries. Any file that declares a function, class, or interface should be loaded with include_once (or require_once) so a redeclaration error is impossible even if several parts of your app pull it in.
• Shared headers/footers. A header.php that should render once per page.
• Constants and config. Files that define() constants — redefining a constant raises a warning.

In modern PHP, Composer's autoloader usually replaces manual inclusion for classes, but include_once is still everywhere in legacy code, templates, and small scripts.

Common gotchas

• It guards against double inclusion, not load order. include_once does not magically resolve dependencies between files; it only prevents the same file from loading twice.
• The "once" check is per request, not persistent — every HTTP request starts with a clean slate.
• Symlinks and different relative paths to the same file are de-duplicated by real path, but a file reachable through two genuinely different paths (e.g. different mounts) may be included twice.

Conclusion

include_once includes a file exactly once per request, preventing fatal redeclaration errors and duplicate output. Reach for it (or require_once) whenever a file defines functions, classes, or constants. Choose between the include_* and require_* families based on whether a missing file should be a recoverable warning or a hard stop.

Practice