> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# PHP Include Once Statement
The `include_once` statement is a PHP language construct that evaluates and incorporates a specified file into the current script during execution. It differs from the standard `include` statement by maintaining an internal registry of included files; before attempting an inclusion, PHP verifies if the file has already been loaded during the current request. If it has, PHP bypasses the operation, preventing fatal errors caused by duplicate declarations of functions, classes, or interfaces.
## Syntax
Because `include_once` is a language construct and not a standard function, parentheses are optional.
```php theme={"dark"}
include_once 'path/to/file.php';
// Parentheses are permitted but generally discouraged for language constructs
include_once('path/to/file.php');
```
## Execution Mechanics
**Path Resolution**
PHP resolves the target file path based on the `include_path` directive defined in `php.ini`. If the file is not found within the `include_path`, PHP falls back to checking the directory of the calling script, followed by the current working directory. Absolute paths and explicitly relative paths (those starting with `./` or `../`) bypass the `include_path` resolution entirely.
**Error Handling**
If PHP cannot locate or access the specified file, `include_once` emits an `E_WARNING` and allows script execution to continue. This contrasts with `require_once`, which emits an `E_WARNING` for the failed stream open followed by a fatal `E_COMPILE_ERROR` that halts script execution entirely. Because `require_once` emits a compile error rather than throwing an `Error` exception, the failure cannot be caught using a `try...catch` block.
**Return Values**
The construct evaluates to different values based on the inclusion state:
* **Initial Success:** Returns `1` by default. If the included file contains a `return` statement in the global scope, `include_once` evaluates to that specific returned value.
* **Already Included:** Returns boolean `true` if the file was previously included during the current request.
* **Failure:** Returns boolean `false` if the file cannot be found or read.
```php theme={"dark"}
// Assuming 'config.php' returns an array: return ['debug' => true];
$config = include_once 'config.php'; // $config is ['debug' => true]
// Subsequent call during the same request
$status = include_once 'config.php'; // $status is true (boolean)
```
## Scope Inheritance
When a file is included, the code within it inherits the variable scope of the exact line where the `include_once` statement is executed.
* **Variables:** Any variables available at the invocation line in the calling file are accessible within the included file. If `include_once` is called within a function, the included code behaves as if it were defined inside that function, restricting its variables to that local scope.
* **Functions and Classes:** Regardless of where the `include_once` statement is executed (even within a local function scope), all functions and classes defined within the included file are automatically injected into the global scope.
* **Magic Constants:** Magic constants like `__FILE__` and `__DIR__` evaluated inside the included file will resolve to the path and directory of the *included* file, not the calling file.
Tired of Poor PHP Skills? Fix That With Deep Grasping!
Learn More
